Last Updated November 2014

Package managers have become an integral part of web development. Composer is made available to all PHP apps on Pagoda Box. This doc walks through how Composer is used on Pagoda Box and what you need to know to use it. After reading it, you should be familiar with:

  • Using Composer on Pagoda Box
  • Loading libraries & packages on deploy
  • Showing off your ninja dev skills with iron-fisted package Management

How Package Management Works on Pagoda Box

Packages / dependencies / libraries are loaded into your codebase as your code services are built and prepped for deploy. Each time you deploy your code, a "build exec" hook runs and loads all dependencies into your codebase.

The default build exec and lib_dir settings are below.

Default Build Execs & Library Directories


      - "composer install --no-interaction --prefer-source"
    lib_dir: vendor

Composer.phar is Pre-Installed in PHP Build Instances

The composer php archive is pre-installed in all PHP build instances and is accessed through the composer alias.

The above default is shown in the format in which it's configured in the Boxfile. If the defaults work for your application, you don’t need to include them in your Boxfile. If you need something different than the default, you can provide your own in your Boxfile.

For more information about build hooks, check out the Build & Deploy Hooks doc.

Commit Your composer.lock to Your Repo

If using composer, be sure to commit your composer.lock to your repo. This tells Composer what specific versions of dependencies to use. Without it, Composer must iterate through every single declared dependencies and find the most recent version, then check to see if that version is compatible with all other dependencies. This is an incredibly memory-heavy process that can cause your deploy to fail.

Build instances have a limited amount of RAM. Without a lock file, Composer will likely run out of memory and your deploy will "hang", waiting for Composer to complete. Eventually the hook will timeout and the transaction will continue, but your dependencies will not get loaded.

Composer Only Runs Once

Because code for all code services is prepped and built at the same time, Composer only runs once and should load all dependencies for all code services. For any users of Pagoda v1, this is a significant improvement.

Package Management in Your Boxfile

How your apps handles packages & libraries can be configured in your Boxfile. Packages and dependencies are loaded into your codebase during the build phase of the deploy process. Everything related to your app’s build is handled in the build section of your Boxfile. There are three main Boxfile configs related to package management: build exec, lib_dir, and reuse_libs.

Build exec

The build exec specifies what command to run to prepare your code for deploy. If the default build exec doesn’t suit your needs, simply provide your own command.

exec YAML

      - "composer install --no-interaction --prefer-source"

The lib_dir config tells Pagoda Box where Composer should store its dependencies. After the dependencies have been downloaded, the lib_dir is packaged into a “library archive” which is used on subsequent deploys. This way, packages don’t have to be re-downloaded and future deploys will go much faster.

Note: It is possible to have multiple library directories. All directory paths should be relative to the root of your repo.

lib_dir YAML

    lib_dir: app/vendor
    # For Multiple lib_dirs
      - app/vendor
      - app/packages

The reuse_libs config allows you to specify whether or not you want a library archive to be stored and reused on subsequent deploys. If set to false, packages will be re-downloaded on all deploys, increasing deploy times.

reuse_libs YAML

  # default setting
    reuse_libs: true

Full Boxfile Config Example YAML

      - "composer install --no-interaction --prefer-source"
    lib_dir: vendor
    reuse_libs: true

Managing Library Archives

With reuse_libs set to “true,” dependencies downloaded during a deploy are stored in a library archive. This library archive provides a starting point for all subsequent deploys and keeps packages from having to be re-downloaded, drastically reducing deploy times.

At some point, you may need to flush and rebuild your library archive. This can be done from either your Boxfile or your Dashboard.

Flushing Libraries from the Boxfile

To flush libraries through the Boxfile, simply set reuse_libs to false. On your next deploy, previously loaded packages are ignored and all dependencies are reloaded in the build process.

Flushing Libraries in Your Dashboard

To flush libraries through your dashboard, click “Current Build & Libraries” button above your code services. Here you can take three possible actions, two of which will flush your app’s library archive.

Flush Libraries

“Flush Llibraries” will flush the library archive stored on Pagoda Box. This will NOT affect your running app. It only clears out previously loaded dependencies. On your next deploy, packages will be reloaded and your library archive will be rebuilt (unless you have reuse_libs set to “false”).

Flush & Rebuild

“Flush & Rebuild” clears out previously loaded dependencies and redeploys your app from your current deploy point. In the deploy process, your dependencies are reloaded, your library archive is rebuilt, build & deploy hooks are re-run, and the newly built instances are deployed into production.

If you have any questions, suggestions, or corrections, let us know.