getting started  »  applications

Applications

The application object of the Pop PHP Framework is the main object that helps control and provide access to the application's elements, configuration and current state. Within the application object are ways to create, store and manipulate common elements that you may need during an application's life-cycle, such as the router, service locator, event manager and module manager. Additionally, you can also have access to the config object and the autoloader, if needed.

Application Setup

The application constructor is flexible in what it can accept when setting up your application. You can pass it a configuration array or object, or individual instances of the objects your application will need:

Configuration Array

In the example below, a configuration array is passed into the application object, which then wires up everything needed.

$config = [
    'routes' => [
        '/' => [
            'controller' => 'MyApp\Controller\IndexController',
            'action'     => 'index'
        ]
    ],
    'events' => [
        [
            'name'     => 'app.init',
            'action'   => 'MyApp\Event::doSomething',
            'priority' => 1000
        ]
    ],
    'services' => [
        'session' => 'Pop\Session\Session::getInstance'
    ]
];

$app = new Pop\Application($config);
$app->run();
Injecting Objects

The example below is the equivalent to the above example, except instead of using a configuration array, the required objects are created and passed into the application object directly.

$router = new Pop\Router\Router();
$router->addRoute('/', [
    'controller' => 'MyApp\Controller\IndexController',
    'action'     => 'index'
]);

$service = new Pop\Service\Locator(['session' => 'Pop\Session\Session::getInstance']);
$events  = new Pop\Event\Manager('app.init', 'MyApp\Event::doSomething', 1000);
$app     = new Pop\Application($router, $service, $events);
$app->run();

Autoloader

You can pass the composer autoloader object into the application object and access it through the application object if it is needed to register other components of the application.

$autoloader = include __DIR__ . '/vendor/autoload.php';

$app = new Pop\Application($autoloader);

$app->autoloader->add('Test', __DIR__ . '/src/Test');   // PSR-0
$app->autoloader->addPsr4('MyApp\\', __DIR__ . '/src'); // PSR-4

If needed, you can autoload your application's source through the application constructor by setting a prefix and src keys in the configuration array:

$autoloader = include __DIR__ . '/vendor/autoload.php';

$app = new Pop\Application($autoloader, [
    'prefix' => 'MyApp\\',
    'src'    => __DIR__ . '/src'
]);

Basic API

Once the application object and its dependencies are wired up, you'll be able to interact with the application object through the appropriate API calls.

  • $app->bootstrap($autoloader = null) - Bootstrap the application
  • $app->init() - Initialize the application
  • $app->registerConfig($config) - Register a new configuration object
  • $app->registerRouter($router) - Register a new router object
  • $app->registerServices($services) - Register a new service locator
  • $app->registerEvents($events) - Register a new event manager
  • $app->registerModules($modules) - Register a new module manager
  • $app->registerAutoloader($autoloader) - Register an autoloader with the application
  • $app->mergeConfig($config, $preserve = false) - Merge config values into the application
  • $app->register($module, $name) - Register a module with the module manager
  • $app->run($exit, $forceRoute) - Run the application

You can access the main elements of the application object through the following methods:

  • $app->autoloader() - Access the autoloader
  • $app->config() - Access the configuration object
  • $app->router() - Access the router
  • $app->services() - Access the service locator
  • $app->events() - Access the event manager
  • $app->modules() - Access the module manager

Also, magic methods expose them as direct properties as well:

  • $app->autoloader - Access the autoloader
  • $app->config - Access the configuration object
  • $app->router - Access the router
  • $app->services - Access the service locator
  • $app->events - Access the event manager
  • $app->modules - Access the module manager

Advanced API

The application object has some additional methods to help access objects and elements within the application object:

  • $app->register($module, $name); - Register a module
  • $app->unregister($name); - Unregister a module
  • $app->isRegistered($name); - Check if a module is registered
  • $app->module($module) - Get a module object
  • $app->addRoute($route, $controller); - Add a route
  • $app->addRoutes($routes); - Add routes
  • $app->setService($name, $service); - Set a service
  • $app->getService($name); - Get a service
  • $app->removeService($name); - Remove a service
  • $app->on($name, $action, $priority = 0); - Attach an event
  • $app->off($name, $action); - Detach an event
  • $app->trigger($name, array $args = []); - Trigger an event

Running an Application

Once you've configured your application object, you can run the application by simply executing the run method. Any inbound request to a script that is set up as outlined here will be processed through the application object and its supporting objects.

$app->run(); // $app->run($exit, $forceRoute);

The first parameter $exit is a boolean flag that will be passed down to the router and allow the router to determine how to exit the application if a route is not found. By default, it's set to true, so the application exits out whenever a route is not found. However, if you wanted the application to not exit for any reason after a failed route match, you can set that flag to false.

The second optional parameter $forceRoute allows for an override and forces the application to run the provided route. This is useful when the application object is passed to other services, for example, a queue service, that need to trigger specific routes to run at scheduled times.