Composer
Overview
Composer dependency management is the de facto standard for managing PHP dependencies. Sugar platform ships with all required code bundled and optimied together for our developers. The installer will, however, deploy both composer.json and composer.lock in the web root directory as a reference of all dependencies which are controlled by Composer.
Autoloader
Sugar has a custom autoloader that is PSR-0 and PSR-4 compliant and integrates with Composer's mapping definitions.
Integrations
When updating the Composer configuration, Composer will generate different mappings based on the settings of every dependency:
- Class map
- PSR-0 map
- PSR-4 map
- Include paths (deprecated)
SugarCRM's autoloader uses those generated maps directly to initialize itself and to figure out how to load different classes.
Internals
To prevent endless file stats, Sugar's autoloader maintains a full list of all files at its disposal. This list is only generated once and is maintained in ./cache/file_map.php. Most of the Sugar codebase uses the autoloader to determine whether a file is available rather than performing expensive file_exists calls.
A second file, stored in ./cache/class_map.php , maintains a flat list of class-name-to-file mappings. When you make any changes to the file system, clear both files before testing new code.
Optimization
When updating dependencies through Composer, Sugar team uses the optimize flag: composer update --optimize-autoloader --no-dev". By doing so, Composer will scan all files in the packages it manages and create a full list of PSR-0 and PSR-4 class name to file mappings, instead of performing this lookup on the fly by the autoloader itself on runtime.
Frequently Asked Questions
Is the composer package required to install a Sugar instance?
No. The Sugar installer ships with all required code bundled together. The installer process does not execute any Composer commands. The installer will deploy both composer.json and composer.lock in the web root directory as a reference of all dependencies which are controlled by Composer.
Why does Sugar ship ./composer.json and ./composer.lock if the installer doesn't rely on them?
Composer is used internally during development to manage Sugar's dependencies on third-party libraries and packages. The Composer files are shipped during development to manage Sugar's dependencies on third-party libraries and packages. The composer files are shipped with the product to give our customers the ability to expand from them.
Is the Composer package required to upgrade a Sugar instance?
No. The Sugar upgrader ships, just like the installer, with all required code bundled together. The upgrade process will validate the present Composer configuration and verify if it is compatible with the upgrade. In the case of a custom configuration, the upgrade process will report any issues which need to be resolved by the system administrator before the upgrade can proceed.
Why are there no wildcards in the version constraints? Doesn't composer.lock keep track of exact version numbers?
The lock file is designed to lock the dependencies to a specific version, but to protect our customers from unintentionally pulling in newer versions of dependencies owned by SugarCRM, we have chosen to use explicit version numbers in the composer.json file too.
May I change the version number of a package?
You cannot change version numbers for packages added by Sugar. Sugar will always configure exact version numbers for all of its dependencies. Changing these version numbers will result in an unsupported platform. The version constraints of packages not owned by Sugar may be modified at the developer's discretion.
Can I use Composer's autoloader?
We strongly recommend against using Composer's autoloader. The Sugar autoloader is fully compatible with the PSR-0 and PSR-4 autoloading recommendations from PHP-FIG, which makes the registration of an additional autoloader like the one from Composer redundant. Sugar's autoloader consumes the different mappings which are generated by Composer directly.
How can I optimize the autoloader?
Sugar ships with an optimized class map out of the box, which is pre-generated through Composer. This class map contains all different class to file mappings known to the dependencies managed by Composer. When customizing the Composer configuration, it is sufficient to run composer update --optimize-autoloader which will refresh the class map. SugarCRM's autoloader takes full advantage of this optimization.
Can I load customizations in Sugar through Composer?
Although not yet available out of the box, we are investigating this as a future capability.
Can I move the vendor directory out of the web root?
You cannot currently move the vendor directory, but we are investigating this as a future capability.
The Composer integration in Sugar is not flexible enough for me. What can I do?
We continuously strive to make our platform better and to facilitate both end users and developers. Our goal is to deliver a state-of-the-art environment. Do not hesitate to reach out to Sugar Support if we have overlooked your use case or if there too many constraints in the current implementation to make this a useful feature.