Advance Configuration

Apiato provides a fluent configuration API that allows you to customize how your application loads resources, routes, providers, and more. Apiato uses a set of sensible defaults for loading resources and configuring components. This documentation explains how to use the Apiato::configure() method and its various options to customize your Apiato application.

Basic Usage

To use the configuration builder, you can call the Apiato::configure() method in your application's bootstrap file (e.g., bootstrap/app.php).

$apiato = Apiato::configure(basePath: '/path/to/app')->create();

Core Configuration Methods

configure

Initializes the Apiato configuration builder with an optional base path.

$builder = Apiato::configure('/path/to/app');

If no base path is provided, Apiato will attempt to determine it from:

1. The APP_BASE_PATH environment variable
2. The Composer autoloader location

useSharedPath

Sets the path for shared components (defaults to app/Ship).

Apiato::configure()->useSharedPath('/path/to/shared');

Resource Loading Methods

Each of these methods accepts directory paths or glob patterns.

withConfigs

Registers configuration file paths.

Apiato::configure()->withConfigs(
    shared_path('Configs'),
    '/app/Containers/ExampleSection/ExampleContainer/Configs',
);

withEvents

Registers event discovery paths.

Apiato::configure()->withEvents(
    shared_path('Listeners'),
    '/app/Containers/ExampleSection/ExampleContainer/Listeners',
);

withCommands

Registers console command paths.

Apiato::configure()->withCommands(
    shared_path('Commands'),
    '/app/Containers/ExampleSection/ExampleContainer/UI/CLI/Commands',
);

withHelpers

Registers helper file paths.

Apiato::configure()->withHelpers(
    shared_path('Helpers'),
    '/app/Containers/ExampleSection/ExampleContainer/Helpers',
);

withMigrations

Registers migration paths.

Apiato::configure()->withMigrations(
    shared_path('Migrations'),
    '/app/Containers/ExampleSection/ExampleContainer/Data/Migrations',
);

Component Configuration Methods

These methods accept optional callbacks for advanced configuration:

withProviders

Configures service provider loading.

Apiato::configure()
    ->withProviders(
        function (\Apiato\Foundation\Configuration\Provider $provider) {
            $provider->loadFrom(
                shared_path('Providers'),
                '/app/Containers/ExampleSection/ExampleContainer/Providers',
            );

            $provider->replace([
                OldProvider::class => NewProvider::class,
            ]);

            $provider->merge([
                CustomProvider::class,
            ]);

            $provider->except([
                UnwantedProvider::class,
            ]);
        },
    );

withSeeders

Configures database seeder loading.

Apiato::configure()
    ->withSeeders(
        function (\Apiato\Foundation\Configuration\Seeding $seeding) {
            $seeding->loadFrom(
                '/app/Containers/ExampleSection/ExampleContainer/Data/Seeders',
            );

            // Custom seeder sorting
            $seeding->sortUsing(function (array $classMapGroupedByDirectory) {
                // Custom sorting logic
                return $sortedClassNames;
            });
        },
    );

withTranslations

Configures translation loading.

Apiato::configure()
    ->withTranslations(
        function (\Apiato\Foundation\Configuration\Localization $localization) {
            $localization->loadFrom(
                shared_path('Languages'),
                '/app/Containers/ExampleSection/ExampleContainer/Languages',
            );

            // Custom namespace builder
            $localization->buildNamespaceUsing(function (string $path) {
                return $namespace;
            });
        },
    );

withViews

Configures view loading.

Apiato::configure()
    ->withViews(
        function (\Apiato\Foundation\Configuration\View $view) {
            $view->loadFrom(
                shared_path('Views'),
                shared_path('Mails/Templates'),
                '/app/Containers/ExampleSection/ExampleContainer/UI/WEB/Views',
            );

            // Custom namespace builder
            $view->buildNamespaceUsing(function (string $path) {
                return $namespace;
            });
        },
    );

withRouting

Configures API and web routing.

Apiato::configure()
    ->withRouting(
        function (\Apiato\Foundation\Configuration\Routing $routing) {
            $routing->prefixApiUrlsWith('api/')
                ->loadApiRoutesFrom('/app/Containers/ExampleSection/ExampleContainer/UI/API/Routes')
                ->loadWebRoutesFrom('/app/Containers/ExampleSection/ExampleContainer/UI/WEB/Routes');

            // Disable API version auto-prefixing
            $routing->disableApiVersionAutoPrefix();

            // Custom API version resolver
            $routing->resolveApiVersionUsing(function (string $file) {
                return $version;
            });
        },
    );

withFactories

Configures model factory resolution.

Apiato::configure()
    ->withFactories(
        function (\Apiato\Foundation\Configuration\Factory $factory) {
            $factory->resolveFactoryNameUsing(function (string $modelName) {
                return $factoryClassName;
            });
        },
    );

withRepositories

Configures repository-model binding.

Apiato::configure()
    ->withRepositories(
        function (\Apiato\Foundation\Configuration\Repository $repository) {
            $repository->resolveModelNameUsing(function (string $repositoryName) {
                return $modelClassName;
            });
        },
    );

create

Finalizes the configuration and returns the Apiato instance.

$apiato = Apiato::configure()->create();

Example

$basePath = dirname(__DIR__);

$apiato = Apiato::configure(basePath: $basePath)
    ->useSharedPath(join_paths($basePath, 'app/Ship'))
    ->withConfigs(
        shared_path('Configs'),
        ...glob($basePath . '/app/Containers/*/*/Configs', GLOB_ONLYDIR)
    )->withRouting(function (Routing $routing) use ($basePath) {
        $routing->prefixApiUrlsWith('api/')
            ->loadApiRoutesFrom(
                ...glob($basePath . '/app/Containers/*/*/UI/API/Routes', GLOB_ONLYDIR)
            )
            ->loadWebRoutesFrom(
                ...glob($basePath . '/app/Containers/*/*/UI/WEB/Routes', GLOB_ONLYDIR)
            );
    })->withFactories()
    ->create();