# Config Reference

PHP-Prefixer works based on Composer (opens new window) as the dependency management tool. It allows you to declare the libraries your project depends on and manages (install/update) them for you. For more information about Composer, please visit https://getcomposer.org/ (opens new window).

Composer is a dependency management tool in PHP. It allows you to declare the libraries your project depends on and manages (install/update) them for you.

To start using Composer in your project, all you need is a composer.json file. This file describes the project's dependencies and may contain other metadata.

Use the extra attribute in the composer.json file to declare arbitrary extra data. PHP-Prefixer declares the service definitions inside the extra attribute with a php-prefixer area.

# Basic Composer Configuration

This is a sample composer.json config to prefix with PPP the namespaces and global objects. Use it as a reference in the extra / php-prefixer section.

{
    "name": "php-prefixer/getting-started",
    "autoload": {
        "psr-4": {
            "Acme\\": "src/"
        }
    },
    "require": {
        "monolog/monolog": "1.0.*"
    },
    "extra": {
        "php-prefixer": {
            "project-name": "PHP-Prefixer Getting Started",
            "namespaces-prefix": "PPP",
            "global-scope-prefix": "PPP_"
    }
}

# Attributes of the PHP-Prefixer configuration

The schema configuration for prefixing includes attributes to improve the prefixing. This is the reference of the available attributes.

Name Description
project-name (*) Name of the project. Only informational. It is used to create the "Header Comment" of processed files. MANDATORY.
namespaces-prefix (*) The prefix for namespaces. For instance: PPP applied to namespace Monolog; generates namespace PPP\Monolog;. MANDATORY.
global-scope-prefix (*) The prefix for global objects such as functions. For instance: PPP_ applied to function base_path() generates function PPP_base_path(). MANDATORY.
disclaimer Flag to disable the rendering of the "Header Comment" of processed files.
add-dependencies Declaration of additional dependencies that cannot be inferred from the Composer schema.
exclude-from-autoload Libraries to be excluded entirely from the final autoload files. Use with caution.
exclude-paths Paths to be excluded entirely from the final ZIP file. Critical files included in the autoloader cannot be excluded. Use with caution.
ignore-from-global-scope Objects to be ignored in the prefixing process. The files are not prefixed, but they are included in the output.
ignore-libraries Libraries to be ignored in the prefixing process. The files are not prefixed, but they are included in the output.
ignore-paths Paths to folders and files ignored in the prefixing process. The files are not prefixed, but they are included in the output.
prefix-extra-folders Additional root folders to be included in the prefixing process. All prefixers are applied to these folders.

# Advanced Composer Extra Configuration

This is a sample composer.json config to prefix with PPP the namespaces and global objects. Use it as a reference for all the available attributes in the extra / php-prefixer section.

{
    "name": "php-prefixer/getting-started",
    "autoload": {
        "psr-4": {
            "Acme\\": "src/"
        }
    },
    "require": {
        "monolog/monolog": "1.0.*"
    },
    "extra": {
        "php-prefixer": {
            "project-name": "PHP-Prefixer Getting Started",
            "namespaces-prefix": "PPP",
            "global-scope-prefix": "PPP_",
            "disclaimer": true,
            "add-dependencies": {
                "nesbot": [
                    "illuminate"
                ]
            },
            "exclude-from-autoload": [
                "symfony/polyfill-php56"
            ],
            "exclude-paths": [
                "bin/",
                "doctrine/inflector/docs",
                "voku/portable-ascii/build",
                "symfony/console/Tests",
                "symfony/contracts/Tests",
                "symfony/debug/Resources/ext/tests",
                "tests"
            ],
            "ignore-from-global-scope": [
                "session",
                "dispatch"
            ],
            "ignore-libraries": [
                "symfony/polyfill-ctype",
                "symfony/polyfill-php54"
            ],
            "ignore-paths": [
                "library/config"
            ],
            "prefix-extra-folders": [
                "bootstrap",
                "config",
                "database",
                "public",
                "resources",
                "routes",
                "tests"
            ]
        }
    }
}

# Ignored Libraries

This is the list of libraries that are ignored by default by the prefixer processor:

# Polyfills

  • symfony/polyfill-apcu
  • symfony/polyfill-ctype
  • symfony/polyfill-php54
  • symfony/polyfill-php55
  • symfony/polyfill-php56
  • symfony/polyfill-php70
  • symfony/polyfill-php71
  • symfony/polyfill-php72
  • symfony/polyfill-php73
  • symfony/polyfill-php74
  • symfony/polyfill-php80
  • symfony/polyfill-iconv
  • symfony/polyfill-intl-grapheme
  • symfony/polyfill-intl-idn
  • symfony/polyfill-intl-icu
  • symfony/polyfill-intl-messageformatter
  • symfony/polyfill-intl-normalizer
  • symfony/polyfill-mbstring
  • symfony/polyfill-util
  • symfony/polyfill-uuid

# FIG Standards

  • fig/cache-util
  • fig/event-dispatcher-util
  • fig/http-message-util
  • fig/link-util
  • psr/cache
  • psr/container
  • psr/event-dispatcher
  • psr/http-client
  • psr/http-factory
  • psr/http-message
  • psr/http-server-handler
  • psr/http-server-middleware
  • psr/link
  • psr/log
  • psr/simple-cache

# Other Libraries

  • paragonie/random_compat
  • ralouphie/getallheaders

# Build Optimization

The prefixing process visits several times file to prefix each dependency. Since the process follows a conservative approach, it also processes files to be "on the safe side".

The prefixer configuration can reduce the number of files and the potential dependencies between libraries and projects to reduce the processing time.

As a rule, if there are no dependencies between two libraries, it is better to prefix them in separate projects.

These are the configuration attributes defined to optimize the prefixing time:

  • exclude-paths, for instance doctrine/inflector/tests, files not used for prefixing and not included in the output.
  • exclude-from-autoload, for instance google/apiclient, a library used to apply prefixes but not included in the final output.
  • ignore-from-global-scope, for instance JsonSerialize, global objects/ helpers that are ignored, not prefixed.
  • ignore-libraries, for instance nesbot/carbon, libraries that are not prefixed and are included in the output without changes.
  • ignore-paths, for instance nesbot/carbon/src/Carbon/Lang, paths to archives that are not prefixed and are included in the output without changes.

To give you an example of a complex library that require extensive prefixing configuration, google/apiclient-services (opens new window). This package includes all possible Google APIs. If you have it on a project, it adds a considerable load of potential dependencies. However, a project would probably use only a couple of services. To reduce the processing time, the exclude-paths declaration can eliminate all the unused services and produce a build with only the required prefixed services. If you separate the original library in different prefixing configurations, the google/apiclient must be processed in all of them to prefix the parent class. However, to avoid duplications in the output, the library google/apiclient must be excluded from the final artifact with exclude-from-autoload.