README

What it does

Reduces boilerplate for bootstrapping and configuration by abstracting common tasks to a simple api. Used by Fusionary's Craft CMS Boilerplate.

Bootstrap

e.g @webroot/index.php

• Reduces your app bootstrap boilerplate code to a single chainable statement.
  • This is especially helpful for achieving consistency when dealing with multiple access points (e.g. multi-site, console app)
• Sets PHP constants, with sensible fallbacks.
• Gracefully loads .env file environment variables.

Configuration files

e.g. @root/config/general.php or any configuration files

• Retrieves environment variables with fallbacks and content-aware type conversion. For example:
  • export MY_BOOL=true → bool
  • export MY_INT=3 → int
• Provides access to HTTP request headers (via yii\web\Request), should your configuration rely on it.
• Provides method to map your entire config to any matching/prefixed environment variables.
  • For example, $config['allowAutoUpdates'] will match CRAFT_ALLOW_AUTO_UPDATES from environment

Prerequisites

"php": ">=7.1.0",
"craftcms/cms": "^3.0.0-RC1",

Installation

composer require fusionary/craftcms-bootstrap

API Documentation

Class Reference / API Documentation

Examples

Web app

e.g. @root/public/index.php

<?php
require_once dirname(__DIR__) . '/vendor/autoload.php';
fusionary\craftcms\bootstrap\Bootstrap::run();

Multi-site web app

e.g. @root/public/site-handle/index.php

<?php
require_once dirname(__DIR__, 2) . '/vendor/autoload.php';
fusionary\craftcms\bootstrap\Bootstrap
    ->setDepth(2) // Set the depth of this script from your project root (`CRAFT_BASE_PATH`) to determine paths
    ->setSite('site-handle') // If the containing folder matches the site handle, you could dynamically set this with `basename(__DIR__)`
    ->run();

Console app

e.g. @root/craft

<?php
require_once dirname(__DIR__) . '/vendor/autoload.php';
exit(Bootstrap::run('console')->setDepth(0)->run()); // Override the default depth of 1, since this script is in `@root`.

Environment variable mapping

Passing your config through Config::mapMultiEnvConfig or Config::mapConfig will map all settings to corresponding environment variables (if they exist).

Settings are converted from their Craft/PHP versions (camel-case) to their environment variable versions (all-caps, snake-case, prefixed — e.g. CRAFT_, DB_).

General config

e.g. @root/config/general.php

<?php
// Example environment:
// export CRAFT_ALLOW_AUTO_UPDATES=true;

use fusionary\craftcms\bootstrap\helpers\Config;

return Config::mapMultiEnvConfig([
    '*' => [
        'allowAutoUpdates' => true,
        'someOtherSetting' => 'foo',

        // Example: get HTTP header from request
        'devServerProxy' => Config::getHeader('x-dev-server-proxy') ?? false,
    ],
    'production' => [
        'allowAutoUpdates' => false,
    ]
]);

// Result:
// return [
//  '*' => [
//    'allowAutoUpdates' => true,
//    'someOtherSetting' => 'foo'
//  ],
//  'production' => [
//    'allowAutoUpdates' => true
//  ]
// ];

Database config

e.g. @root/config/db.php

<?php
// Example environment:
// export DB_DRIVER=mysql
// export DB_SERVER=mysql
// export DB_USER=my_app_user
// export DB_PASSWORD=secret
// export DB_DATABASE=my_app_production
// export DB_SCHEMA=public

use fusionary\craftcms\bootstrap\helpers\Config;

// Pass prefix as 2nd argument, defaults to 'CRAFT_'
return Config::mapConfig([
  'driver' => null,
  'server' => null,
  'user' => null,
  'password' => null,
  'database' => null,
  'schema' => null,
], 'DB_');

// Result:
// return [
//   'driver' => 'mysql',
//   'server' => 'mysql',
//   'user' => 'my_app_user',
//   'password' => 'secret',
//   'database' => 'my_app_production',
//   'schema' => 'public',
// ]

Generate documentation

composer run-script build-docs

Acknowledgements

"Boot" icon by Ben Davis from The Noun Project