CreatesApplication Trait

Purpose and Scope

The CreatesApplication trait provides extension points for package developers to register custom service providers and class aliases during test execution. This trait is included in TestCase and allows test classes to define package-specific providers and aliases that should be registered in the application container alongside the framework's default providers.

For information about the base testing infrastructure, see TestCase: Core Testing Foundation. For details on the broader configuration provider system, see Configuration Provider System. For other testing traits, see HandlesRoutes Trait and HandlesDatabases Trait.

Sources: src/Concerns/CreatesApplication.php1-59

Trait Overview

The CreatesApplication trait is a testing concern that implements the template method pattern, providing four methods that work together to enable package-specific provider and alias registration:

Method	Type	Return Type	Purpose
getPackageProviders	Override Hook	array<int, class-string>	Define service providers to register
getPackageAliases	Override Hook	array<string, class-string>	Define class aliases to register
registerPackageProviders	Implementation	void	Execute provider registration
registerPackageAliases	Implementation	void	Execute alias registration

The trait follows a two-phase design: developers override the get* methods to declare what should be registered, while the register* methods handle the actual registration logic.

Sources: src/Concerns/CreatesApplication.php9-59

Method Relationships

Diagram: Method Call Hierarchy and Data Flow

This diagram illustrates how the four methods interact during the test setup phase. The defineEnvironment() method in TestCase invokes the registration methods, which in turn call the getter methods to retrieve provider and alias definitions.

Sources: src/Concerns/CreatesApplication.php14-58

getPackageProviders Method

Method Signature

src/Concerns/CreatesApplication.php19-22

Purpose

The getPackageProviders method is an override hook that returns an array of service provider class names to be registered with the application. By default, it returns an empty array, and test classes should override this method to specify their package's service providers.

Return Value

Returns an indexed array of fully-qualified service provider class names. Each element must be a string representing a class that implements the service provider interface.

Type: array<int, class-string>

Usage Pattern

Test classes override this method to declare package providers:

The method receives the ApplicationContract instance, allowing providers to be conditionally registered based on application state, though this is rarely needed in practice.

Sources: src/Concerns/CreatesApplication.php14-22

getPackageAliases Method

Method Signature

src/Concerns/CreatesApplication.php29-32

Purpose

The getPackageAliases method is an override hook that returns an associative array of class aliases to be registered. Aliases provide convenient shorthand names for fully-qualified class names, similar to Laravel's facade aliases.

Return Value

Returns an associative array where keys are alias names and values are fully-qualified class names.

Type: array<string, class-string>

Usage Pattern

Test classes override this method to declare package aliases:

Aliases are merged into the existing app.aliases configuration, allowing the registered aliases to coexist with framework-provided aliases.

Sources: src/Concerns/CreatesApplication.php24-32

registerPackageProviders Method

Method Signature

src/Concerns/CreatesApplication.php37-42

Implementation

This method implements the actual provider registration logic:

1. Calls getPackageProviders($app) to retrieve the provider array
2. Iterates through each provider class name
3. Calls $app->register($provider) for each provider

src/Concerns/CreatesApplication.php38-42

Registration Process

The $app->register() method triggers the service provider lifecycle:

• Instantiates the provider class
• Calls the provider's register() method
• Optionally calls the provider's boot() method

Test classes typically do not need to override this method; customization should occur in getPackageProviders().

Sources: src/Concerns/CreatesApplication.php35-42

registerPackageAliases Method

Method Signature

src/Concerns/CreatesApplication.php47-58

Implementation

This method implements alias registration through configuration manipulation:

1. Calls getPackageAliases($app) to retrieve the alias array
2. Returns early if the alias array is empty
3. Retrieves the configuration instance from the application container
4. Retrieves existing aliases from app.aliases configuration
5. Merges package aliases with existing aliases
6. Sets the merged result back to app.aliases configuration

src/Concerns/CreatesApplication.php47-58

Early Return Optimization

The method includes an early return when $aliases is empty src/Concerns/CreatesApplication.php51-53 avoiding unnecessary configuration reads and writes when no aliases are defined.

Sources: src/Concerns/CreatesApplication.php44-58

Integration with TestCase Lifecycle

Diagram: CreatesApplication Integration in Test Lifecycle

This sequence diagram shows how the CreatesApplication trait methods are invoked during the test setup phase. The defineEnvironment() method in TestCase calls the registration methods after creating the application instance but before the test executes.

Sources: src/Concerns/CreatesApplication.php1-59

Relationship to ConfigProviderRegister

Diagram: Relationship Between CreatesApplication and ConfigProviderRegister

The CreatesApplication trait complements the ConfigProviderRegister system. While ConfigProviderRegister manages the 45+ framework providers (20 Hyperf + 25 Hypervel providers), the CreatesApplication trait allows package-specific providers to be added on top of this foundation. Both sets of providers coexist in the application container.

Sources: src/Concerns/CreatesApplication.php1-59 src/ConfigProviderRegister.php11-57

Usage Examples

Basic Provider Registration

A test class registering a single service provider:

The provider will be registered during setUp() before each test method executes.

Provider and Alias Registration

A test class registering both providers and aliases:

Conditional Provider Registration

Using the ApplicationContract parameter for conditional logic:

Though the application is always in testing mode during test execution, this pattern can be useful for feature flags or conditional dependencies.

Sources: src/Concerns/CreatesApplication.php19-58

Common Patterns

Testing Package With Multiple Providers

When testing a package that provides several service providers, all can be registered:

Facade Registration Pattern

Packages that provide facades typically register both the provider and aliases:

The facade can then be used in tests via the alias: MyPackage::someMethod().

No Registration Needed

Many packages don't require custom providers or aliases during testing. In these cases, the methods can remain unoverridden, returning empty arrays by default src/Concerns/CreatesApplication.php21-31

Sources: src/Concerns/CreatesApplication.php19-58

Provider Registration Order

Diagram: Provider and Alias Registration Order

Framework providers from ConfigProviderRegister are registered before package providers from getPackageProviders(). This ensures that package providers can depend on framework services. Aliases are configured last, after all providers have been registered.

Sources: src/Concerns/CreatesApplication.php37-58 src/ConfigProviderRegister.php59-66

Design Rationale

Template Method Pattern

The trait implements the template method pattern with two layers:

1. Override Hooks (getPackageProviders, getPackageAliases): Subclasses override these to provide data
2. Implementation Methods (registerPackageProviders, registerPackageAliases): The trait provides the algorithm

This separation allows consistent registration logic while enabling flexible provider/alias declaration.

Receiving ApplicationContract

Both getter methods receive ApplicationContract $app as a parameter src/Concerns/CreatesApplication.php19-29 providing access to the application instance if needed for conditional logic. This is consistent with other Hypervel callback patterns.

Array Return Types

Returning arrays rather than directly calling registration methods allows:

• Clear separation between declaration and execution
• Easy inspection of registered providers/aliases in tests
• Potential for manipulation or filtering before registration

Alias Merging Strategy

The alias registration merges with existing aliases src/Concerns/CreatesApplication.php56-57 rather than replacing them, ensuring that:

• Framework aliases remain available
• Multiple packages can register aliases without conflicts
• Test-specific aliases coexist with application aliases

Sources: src/Concerns/CreatesApplication.php9-59

Interaction with Other Traits

The CreatesApplication trait works alongside other TestCase concerns:

Trait	Purpose	Relationship to CreatesApplication
HandlesRoutes	Route definition	Independent; both configure different aspects
HandlesDatabases	Migration management	Independent; both configure different aspects

All three traits are composed into TestCase, providing complementary functionality:

• CreatesApplication: Registers providers and aliases
• HandlesRoutes: Defines routes and route groups
• HandlesDatabases: Manages database migrations

For route configuration, see HandlesRoutes Trait. For database setup, see HandlesDatabases Trait.

Sources: src/Concerns/CreatesApplication.php1-59

Summary

The CreatesApplication trait provides a clean extension point for package testing by enabling service provider and class alias registration. Test classes override getPackageProviders() and getPackageAliases() to declare what should be registered, while the trait handles the registration mechanics. This design integrates seamlessly with the TestCase lifecycle, ensuring package services are available during test execution while maintaining separation from the framework's 45+ configuration providers managed by ConfigProviderRegister.

Sources: src/Concerns/CreatesApplication.php1-59 src/ConfigProviderRegister.php1-88