Download the PHP package iviphp/framework without Composer

Ivi Framework

Application bootstrapping, service providers, dependency coordination and console integration for the IviPHP ecosystem.

iviphp/framework provides the central runtime used to assemble an IviPHP application. It coordinates the service container, configuration, bootstrap operations, service providers and console commands through a small framework-independent API.

Requirements

• PHP 8.2 or later
• iviphp/config
• iviphp/console
• iviphp/container
• iviphp/contracts
• iviphp/debug
• iviphp/http
• iviphp/support

Installation

Features

• Central application object
• Application base-path management
• Environment detection
• Dependency-container integration
• Configuration integration
• Named bootstrap operations
• Service-provider lifecycle
• Provider service declarations
• Provider registration and boot tracking
• Console command integration
• Closure-backed commands
• Framework service registration
• Safe lifecycle exceptions
• Idempotent application startup
• Framework-independent contracts

Core components

Application

Application represents the running application.

It manages:

• the application base directory;
• the current environment;
• the service container;
• application configuration;
• bootstrap operations;
• service providers;
• the provider boot lifecycle.

FrameworkManager

FrameworkManager coordinates the application and console runtime.

It provides the main management API for:

• creating an application;
• registering bootstrap operations;
• registering service providers;
• resolving container services;
• registering console commands;
• starting the framework;
• executing the console runtime.

Framework

Framework is the public application-facing API.

It wraps FrameworkManager and exposes a compact interface for normal framework usage.

Bootstrapper

Bootstrapper stores named application initialization callbacks and executes them in registration order.

ServiceProvider

ServiceProvider is the reusable base class for framework service providers.

Concrete providers implement service registration and may optionally perform boot-time initialization.

Creating a framework application

The base path must reference an existing directory.

Starting the framework

Starting the framework performs two stages:

1. application bootstrap operations;
2. service-provider booting.

Repeated calls to start() do not execute completed lifecycle stages again.

Application lifecycle

The application lifecycle follows this order:

Bootstrap callbacks execute before service providers are booted.

Provider registration happens when the provider is added to the application.

Application base path

Resolve a path relative to the application base directory:

Example result:

Passing an empty string returns the application base path:

Absolute paths are rejected.

Paths containing parent-directory traversal are also rejected:

Application environment

Create an application for a specific environment:

Retrieve the environment:

Check one environment:

Check several environments:

Change the environment before bootstrapping:

The environment cannot be changed after application bootstrapping begins.

Service container

Retrieve the application container:

Resolve a service:

Check whether a service exists:

The framework automatically registers several core services.

Configuration

Retrieve the application configuration service:

The returned object is the Ivi\Config\Config instance registered in the application container.

A custom configuration object may be supplied during creation:

Custom container

A custom container instance may be supplied:

The framework registers its core services in the supplied container.

Bootstrap operations

Register a named bootstrap callback:

Register another operation:

Bootstrap operations execute in registration order.

Replacing a bootstrap operation

The named operation must already exist when calling Bootstrapper::replace() directly.

Accessing the bootstrapper

List registered operation names:

List completed operations:

Check whether an operation exists:

Check whether an operation completed:

Inspect the current operation during bootstrap:

Creating a service provider

Extend the base service-provider class:

Registering a provider

Register a provider class:

The framework creates the provider by passing the application instance to its constructor.

Register a provider instance:

A provider cannot belong to another application instance.

Registering multiple providers

Providers are registered in the supplied order.

They are also booted in registration order.

Provider lifecycle

A service provider has two lifecycle stages.

Registration

Registration should define:

• instances;
• factories;
• aliases;
• configuration defaults;
• framework services.

Registration happens immediately when the provider is added to the application.

Booting

Booting happens after application bootstrap operations complete.

At boot time, providers may safely coordinate services registered by other providers.

Provider state

Retrieve a provider:

Check its lifecycle state:

The base ServiceProvider class also exposes:

Provider service declarations

Providers may declare the services they supply:

Retrieve declared services:

Check one service:

Find all providers declaring a service:

Service declarations are intended for diagnostics and framework introspection.

They do not automatically register container bindings.

Checking registered providers

Return all registered providers:

Return the provider count:

Manual bootstrap and boot

Bootstrap without booting providers:

Boot providers:

Calling boot() before bootstrap() automatically bootstraps the application first.

Check lifecycle state:

Console integration

The framework integrates iviphp/console.

Retrieve the console API:

Retrieve the console manager:

Registering a console command

Registering command objects

Register several commands:

Replace commands with matching names:

Inspecting console commands

Check whether a command exists:

Return all commands:

Exclude hidden commands:

Return the number of registered commands:

Running the console application

The framework is started before console execution.

A minimal bin/console file may look like this:

Make the file executable:

Run it:

Executing custom console input

execute() starts the framework and executes the supplied input without using the console manager's automatic exception handling.

Accessing the application

Access it through the public contract:

The application contract exposes:

Using Application directly

The higher-level Framework API is recommended, but Application may also be used directly.

Using FrameworkManager directly

Exceptions

Framework lifecycle failures are represented by:

Examples include:

• invalid application base paths;
• invalid relative paths;
• invalid environment names;
• invalid service providers;
• duplicate provider registration;
• provider creation failures;
• provider registration failures;
• provider boot failures;
• invalid bootstrap operations;
• bootstrap failures;
• unavailable services;
• service-resolution failures;
• invalid framework configuration;
• invalid lifecycle operations.

Exception context contains safe diagnostic metadata such as:

• provider class;
• bootstrap operation name;
• service identifier;
• application path;
• lifecycle operation.

It should not contain service values, configuration secrets or request data.

Lifecycle restrictions

To keep framework state predictable:

• environments cannot change after bootstrap begins;
• bootstrap operations cannot change while bootstrapping;
• completed bootstrappers cannot be modified;
• service providers cannot be registered after provider booting starts;
• providers cannot boot before registration;
• providers cannot register after booting begins;
• recursive bootstrap, provider registration and provider boot operations are rejected.

Complete example

Design principles

iviphp/framework follows these principles:

• explicit application lifecycle;
• framework-independent contracts;
• dependency-container coordination;
• ordered bootstrap operations;
• predictable provider registration;
• idempotent application startup;
• separation between registration and booting;
• safe diagnostic context;
• small public application API;
• modular integration with the IviPHP ecosystem.

License

Ivi Framework is open-source software released under the MIT License.

Maintainer

Maintained by Gaspard Kirira and Softadastra.