Skip to content
/ app Public

providers.md

Latest commit

 

History

History
412 lines (309 loc) · 13.7 KB

providers.md

File metadata and controls

412 lines (309 loc) · 13.7 KB

Service Providers

Dependencies and extensions are handled by a dependency container, using Pimple, which can be defined via service providers (Pimple\ServiceProviderInterface).

Included Providers

The Charcoal App comes with several providers out of the box. All of these are within the Charcoal\App\ServiceProvider namespace:

External Providers

The Charcoal App requires a few providers from independent components. The following use their own namespace and are automatically injected via the AppServiceProvider:

Most providers expect the container to provide the config entry, which should hold the application's main configuration.

Basic Services

Dependencies are handled with a Pimple dependency Container.

Basic "App" services are:

  • cache
  • config
    • A \Charcoal\App\AppConfig instance.
  • database
    • The default PDO database.
    • From a pool of database, available through databases.
    • Configured by config['databases'] and config['default_database'].
  • filesystems
    • A (pimple) container of \League\Flysystem\Filesystem
    • Configured by config['filesystem]
    • Also provide a \League\Flysystem\MountManager as filesystem/manager.
  • logger
    • A \Psr\Log\Logger instance.
    • Provided by Monolog.
    • Configured by config['logger']
  • translator
    • A Charcoal\Translator\Translation object for multilingual strings.
    • A Charcoal\Translator\Translator service based on Symfony's Translator.
    • A Charcoal\Translator\LocalesManager for managing available languages.
    • Configured by config['translator'] and config['locales']
    • Provided by charcoal/translator
  • view
    • A Charcoal\View\ViewInterface instance
    • Typically a \Charcoal\View\GenericView object.
    • Configured by config['view']
    • Provided by charcoal/view

App Service Provider

The AppServiceProvider, or charcoal/app/service-provider/app provides the following services:

Service Type Description
notFoundHandler callback For 404 (Not Found) URLs. Slim requirement.
errorHandler callback For 500 (Error) URLs. Slim requirement.
action/factory ActionFactory1 To create actions.
script/factory ScriptFactory2 To create templates.
template/factory TemplateFactory3 To create templates.
widget/factory WidgetFactory4 To create widgets.
  1. \Charcoal\App\Action\ActionFactory
  2. \Charcoal\App\Script\ScriptFactory
  3. \Charcoal\App\Template\TemplateFatory
  4. \Charcoal\App\Widget\WidgetFactory

All factories are implementations of \Charcoal\Factory\FactoryInterface

Cache Service Provider

External Provider

See the charcoal/cache for more information on using the cache service.

The CacheServiceProvider, or charcoal/app/service-provider/cache provides the following servicers:

Service Type Description
cache \Stash\Pool The default PSR-6 cache pool.

Also available are the following helpers:

Helper Service Type Description
cache/config CacheConfig1 Cache configuration.
cache/builder CacheBuilder2 Cache pool builder.
cache/available-drivers array3 Available drivers on the system.
cache/drivers \Pimple\Contianer Map of all the available Stash driver instances.
cache/driver DriverInterface4 The Stash driver used by the default pool, cache.
  1. \Charcoal\Cache\CacheConfig
  2. \Charcoal\Cache\CacheBuilder
  3. \Stash\DriverList
  4. \Stash\Interfaces\DriverInterface

Cache Config

Key Type Default Description
types array [ 'memory' ] The cache types to attempt to use, in order.
default_ttl int 0 Default time-to-live, in seconds.
prefix string charcoal The cache prefix, or namespace.

A full example, in JSON format:

{
    "cache": {
        "types": [ "memcache", "memory" ],
        "default_ttl": 0,
        "prefix": "charcoal"
    }
}

Database Service Provider

The DatabaseServiceProvider, or charcoal/app/service-provider/database provides the following services:

Service Type Description
database \PDO The default database PDO object.
databases \Pimple\Container A map (container) of all the available PDO instances.

Also available are the following helpers:

Helper Service Type Description
database/config DatabaseConfig1 Default database config container.
databases/config \Pimple\Container A map (container) of all the available PDO instances.
  1. \Charcoal\App\Config\DatabaseConfig

Database Config

The databases are configured with the following options:

Key Type Default Description
databases array
default_database string

The database config is as follow:

Key Type Default Description
type string mysql The database driver type.
hostname string localhost The database hostname or IP address.
username string '' The username with access to this database / tables.
password string '' The password, for username.
database string '' The database name for this project.
disable_utf8 bool false Set to true to disable automatic utf-8.

Or, in JSON format:

{
    "databases": {
        "foobar": {
            "type": "mysql",
            "hostname": "dbserver.example.com",
            "username": "dbuser",
            "password": "dbpassword",
            "disable_utf8": false
        }
    },
    "default_database": "foobar"
}

Filesystem Service Provider

The FilesystemServiceProvider, or charcoal/app/service-provider/filesystem provides the following services:

Service Type Description
filesystems \Pimple\Container A list of \League\Flysystem\Filesystem
filesystem/manager \League\Flysystem\MountManager A mount manager.

Also available are the following helpers:

Helper Service Type Description
filesystem/config FilesystemConfig1 Default filesystem config container.
  1. \Charcoal\App\Config\FilesystemConfig

Filesystem Config

Key Type Default Description
connections array ...
default_connection string 'public'

Default Connections

There are 2 connections alway available: private and public.

By default, the public connection represents a local filesystem with the the web-visible root path of the project (the www folder) set as the path.

By default, the private connection represents a local filesystem with the base path of the project set as the path.

Logger Service Provider

The LoggerServiceProvider, or charcoal/app/service-provider/logger provides the following services:

Service Type Description
logger \Psr\Log\LoggerInterface A PSR-3 compliant logger.

A \Monolog\Logger is actually provided by default in the App package.

Also available are the following helpers:

  • logger/config
    • A \Charcoal\App\Config\LoggerConfig instance holding the logger configuration.

Logger Config

Key Type Default Description
active bool true
handlers array
processors array

Possible handlers are stream and console. Possible processors are memory-usage and uid.

{
    "logger": {
        "active": true,
        "handlers": {
            "stream": {},
            "console": {}
        },
        "processors": {
            "memory_usage": {},
            "uid": {}
        }
    }
}

Translator Service Provider

External Provider

See the charcoal/translator for more information on using the translator service.

The TranslatorServiceProvider, or charcoal/translator/service-provider/translator provides the following services:

  • translator

Also available are the following helpers:

  • locales/config

Translator Config

Key Type Default Description
locales array
translator array

Or, in JSON format:

"locales": {
    "languages": {
        "de": {},
        "en": {},
        "es": {
            "active": false
        },
        "fr": {}
    },
    "default_language": "fr",
    "fallback_languages": [
        "en", 
        "fr"
    ],
    "auto_detect": true
},
"translator": {
    "loaders": [
        "xliff",
        "json",
        "php"
    ],
    "paths": [
        "translations/",
        "vendor/charcoal/app/translations/"
    ],
    "debug": false,
    "cache_dir": "cache/translator",
    "translations": {
        "messages": {
            "de": {
                "hello": "Hallo {{ name }}",
                "goodbye": "Auf Wiedersehen!"
            },
            "en": {
                "hello": "Hello {{ name }}",
                "goodbye": "Goodbye!"
            },
            "es": {
                "hello": "Hallo {{ name }}",
                "goodbye": "Adios!"
            },
            "fr": {
                "hello": "Bonjour {{ name }}",
                "goodbye": "Au revoir!"
            }
        },
        "admin": {
            "fr": {
                "Save": "Enregistrer"
            }
        }
    }
}

View Service Provider

External Provider

See the charcoal/view for more information on using the view service.

The ViewServiceProvider, or charcoal/view/service-provider/view provides the following services:

Service Type Description
view ViewInterface1 A Charcoal view instance.
view/renderer Renderer2 A PSR-7 view / renderer.
  1. \Charcoal\View\ViewInterface, typically a \Charcoal\View\GenericView
  2. \Charcoal\View\Renderer

Also available are the following helpers:

  • view/config
    • The main View configuration \Charcoal\View\ViewConfig
  • view/engine
    • The default View engine (\Charcoal\View\EngineInterface)

View Config

Unlike the other services, the view config is not defined inside this module but in the charcoal/view module.

Key Type Default Description
paths array [] The list of paths where to serach for templates.
engines array []
default_engine string mustache

Or, in JSON format:

{
    "view": {
        "paths": [
            "templates/",
            "vendor/charcoal/admin/templates/"
        ],
        "engines": {
            "mustache": {}
        },
        "default_engine": "mustache"
    }
}