PHP Composer

About Composer

Composer is a tool for managing dependencies in PHP projects. The Composer module in ispmanager allows installing and updating libraries and packages automatically.

For example, you need the monolog/monolog logging library. You can specify the package name and version range (or just the package name), and the Composer module will:

1. Check if dependencies for monolog/monolog are installed and download and install them if necessary.
2. Download and install the monolog/monolog library.
3. Add dependency information to the project configuration file.
4. Generate an autoload.php file to autoload classes from the library into your project.
5. Update the dependency if necessary when a new version is released.

Composer installation

Composer is installed in the root directory of the site for which it is enabled.

The version of Composer depends on the PHP version for the site:

• the latest version of Composer requires PHP 7.2 and higher
• for PHP 5.3–7.1, Composer 2.2.x are installed

To install Composer:

1. Log in to the panel with superuser rights.
2. Navigate to Software configuration → Web Server (WWW).
3. Check the PHP Composer box.
4. Click Save.

Composer will be installed in the background mode.

To make Composer available for use, enable it for users and sites.

Enabling Composer

For users

1. Log in to the panel with an administrator-level account or above.
2. Navigate to the Users section.
3. Select a user and click  Edit.
4. In the form that opens, go to the Access block and check the box PHP Composer. 

5. Click Save.

   

For sites

1. Go to the Sites section.
2. Select a site and click  Edit.
3. In the form that opens, go to the Handler (PHP) block and check the PHP Composer box.

4. Click Save.

   

Managing dependencies with Composer

1. Navigate to the Sites section.
2. Select a site and click PHP on the toolbar.
3. In the form that opens, click PHP Composer on the toolbar.

The Installed PHP packages form will open where you can manage dependencies.

Versions of dependencies

When installing a dependency, you can specify either a particular version of it or a range of acceptable versions. For example:

• if the 1.2.3 version is specified, this version will be installed
• if the ^1.2.3 version is specified, the latest compatible version will be installed, but not lower than 1.2.3 and not higher than 2.0.0

Installation

Dependencies and information about them are stored in the site directory:

• Dependencies are installed in the vendor/ directory
• Dependency information is written into the composer.json configuration file
• Information about the specific installed version is registered in the composer.lock file. The composer.lock file is used to lock the versions of dependencies

If the software you are installing depends on other software, it will also be installed automatically.

There are two ways to install a dependency: quick install and using a configuration file.

Quick install

Allows to install a dependency with minimal settings.

1. Click on the toolbar.
2. Specify the package name(-s) and versions of all packages to be installed (optional).
3. Click Install.

By default, dependencies are installed from the Packagist repository. If you need to install a dependency from another repository, install it using the composer.json configuration file by specifying the repository in the file.

Using a configuration file

Allows installing a dependency with advanced settings, from a custom repository or using a custom .json configuration file.

1. Click Configuration file. The composer.json configuration file will open.

   Details

   The composer.json file is the main Composer configuration file which contains dependency settings: names, versions, repositories, etc.:

   composer.json example

   {
       "require": {
               "monolog/monolog": ">=1.0.2 <2.1.2"
       },
       "description": "This example",
       "keywords": ["testing", "example"],
       "type": "project",
       "version": "1.0.0",
       "homepage": "https://example.com",
       "readme": "readme.md",
       "license": "MIT",
       "authors": [{
               "name": "User",
               "email": "user@example.com",
               "homepage": "https://www.example.com",
               "role": "Developer"
       }],
       "support": {
               "email": "support@example.org"
       }
   }

   Commentary

   • require — library name and version to be installed — required field
   • description — project description
   • keywords — keywords for project search in the repository
   • type — type: library, project, metapackage or composer-plugin
   • version — project version
   • homepage — project home page
   • readme — path to the readme file
   • license — project license type
   • authors — information about project authors:
     • name — author name
     • email — author email address
     • homepage — author home page
     • role — project role
   • support — support team email address
2. Copy the contents of your file into the configuration file.
3. Click Save and close.

When saving, the correctness of the JSON format is automatically checked and the installation of packages is emulated with the following command:

/bin/sh -c cd\ /var/www/cm/data/www/example.com\;./composer.phar\ install\ --dry-run

Once the file is saved, the specified dependencies are automatically installed and appear in the Installed PHP packages list.

Update

To update installed versions of dependencies, click Update. This will install the latest available versions of dependencies that satisfy the version constraints in composer.json and will update composer.lock.

Shell client

The Shell client allows running additional Composer commands. The terminal is launched on behalf of the site owner. When the terminal opens:

• the working directory is changed to the site's home directory
• the path to the executable file of the PHP version selected for the site is added to the PATH environment variable

Shell commands must contain the path to the composer.phar executable:

./composer.phar COMMAND

Removal

To remove a dependency, select it from the list and click .

If the dependency being removed is required by other dependencies, an error will occur.

Using dependencies in a project

To use the installed dependencies in your project, specify the path to the autoload.php file in the php section:

require_once('vendor/autoload.php')

<?php
require_once('vendor/autoload.php');
use Monolog\Level;
use Monolog\Logger;
use Monolog\Handler\StreamHandler;
$logger = new Logger('channel-name');
$logger->pushHandler(new StreamHandler('app.log', Logger::DEBUG));
$logger->info('This is log');
$logger->warning('This is log warning');
$logger->error('This is log error');
?>

Backups

When you create a site backup, the site's Composer settings and installed libraries are backed up.

If Composer is disabled in the panel when you restore a user from a backup, the user and their site will be imported with dependencies already installed, but an error record will be added to the recovery log. For the user to continue using Composer, install it in the panel and enable it for the user and the site.

Composer logging

Operations with Composer are written to the logs:

• /usr/local/mgr5/var/phpcomposerctl.log  — contains command calls and errors.
  To change the logging level, add the following line to the /usr/local/mgr5/etc/debug.conf configuration file:

  phpcomposerctl.*        9

• /usr/local/mgr5/var/ispmgr.log — logs panel processes related to module operation.
  To change the logging level of the Composer module in the panel log, navigate to the Logging settings section → Ispmanager - PHP (ispmgr.php). 

Disabling Composer

After disabling Composer for a site or removing it in the Software configuration section, the installed dependencies are not removed.

Protecting Composer service data​

When Composer is enabled, the following service files and directories are created in the site's home directory:

• composer.phar — executable Composer file (only works with the CLI version of PHP)
• composer.json — file describing all project dependencies
• composer.lock — file with a list of all installed dependencies and their versions
• vendor/ — directory to which dependencies are installed
• .cache/ — directory storing cache of downloaded dependencies
• .config/ — directory containing configuration settings and public keys
• .local/ — directory that may store additional Composer data

To prevent service files and directories from being accessed via a browser, special includes are added to the configuration files of web servers for sites. If Nginx + Apache are installed, includes are added to both configuration files.

After disabling Composer, if dependencies were installed for the site, includes in the configuration files are preserved. This is necessary so that service files and directories do not become accessible from a browser after disabling. If the vendor/ directory and the composer.json file were manually removed from the site directory, the includes will be deleted.

Example of an include:

location ~* ^(/composer\.(json|lock|phar)$)|(/(vendor|.config|.cache|.local)/) {
    deny all;
}

<LocationMatch "^(/composer\.(json|lock|phar)$)|(/(vendor|.config|.cache|.local)/)">
	<IfModule mod_authz_core.c>
		# Apache 2.4
		<RequireAny>
		Require all denied
		</RequireAny>
	</IfModule>
	<IfModule !mod_authz_core.c>
		# Apache 2.2
		Order Deny,Allow
		Deny from All
	</IfModule>
</LocationMatch>

context exp: ^(/composer\.(json|lock|phar)$)|(/(vendor|.config|.cache|.local)/) {
  allowBrowse 0
}