diff --git a/src/.vitepress/config.js b/src/.vitepress/config.js index 120bc15b..04e9a2e6 100644 --- a/src/.vitepress/config.js +++ b/src/.vitepress/config.js @@ -205,7 +205,8 @@ export default { {text: 'Making HTTP Requests', link: '/cookbook/making-http-requests'}, {text: 'Using htmx for Partial Page Reloads', link: '/cookbook/using-htmx-for-partial-reloads'}, {text: 'Disabling CSRF Protection', link: '/cookbook/disabling-csrf-protection'}, - {text: 'Sentry Integration', link: '/cookbook/sentry-integration'} + {text: 'Sentry Integration', link: '/cookbook/sentry-integration'}, + {text: 'Using Yii in Third-Party Applications', link: '/cookbook/using-yii-in-third-party-apps'} ] }, { diff --git a/src/cookbook/index.md b/src/cookbook/index.md index efddda87..7e5acdbb 100644 --- a/src/cookbook/index.md +++ b/src/cookbook/index.md @@ -17,6 +17,7 @@ This book conforms to the [Terms of Yii Documentation](https://www.yiiframework. - [Using htmx for partial page reloads](using-htmx-for-partial-reloads.md) - [Disabling CSRF protection](disabling-csrf-protection.md) - [Sentry integration](sentry-integration.md) +- [Using Yii in third-party applications](using-yii-in-third-party-apps.md) - [Working on Windows](working-on-windows.md) - [Opening files directly in PhpStorm](opening-files-in-phpstorm.md) - [Configuring Xdebug](configuring-xdebug.md) diff --git a/src/cookbook/using-yii-in-third-party-apps.md b/src/cookbook/using-yii-in-third-party-apps.md new file mode 100644 index 00000000..215fc4e7 --- /dev/null +++ b/src/cookbook/using-yii-in-third-party-apps.md @@ -0,0 +1,125 @@ +# Using Yii in third-party applications + +Sometimes a project already has an entry point owned by another framework, CMS, or legacy application, but you still +want to reuse Yii services: configuration, DI definitions, domain services, logging, mailers, database connections, or +console-oriented application code. + +Yii3 has no global application singleton. Bootstrap the Yii container explicitly and pass the services you need to the +third-party code. + +## Bootstrap the Yii container + +Create a small adapter in the host application, for example `bootstrap-yii-services.php`: + +```php +getContainer(); + $bootstrap = $runner->getConfig()->get('bootstrap-console'); + + (new BootstrapRunner($container, $bootstrap))->run(); + + return $container; +} +``` + +The console runner is used only as a convenient way to build configuration and DI container groups. The code does not +call `$runner->run()`, so it does not start a Yii console application and does not call `exit()`. + +Use `ConsoleApplicationRunner` when you need common services and console-safe services. Use `HttpApplicationRunner` +instead only when you intentionally need web-specific definitions from the `di-web` group, such as PSR-17 HTTP factories +or web middleware dependencies. + +## Get Yii services from the host application + +Use the adapter from the third-party application: + +```php +get(ApplicationParams::class); + +echo $params->name; +``` + +In real integrations, prefer getting your own application services instead of framework infrastructure. For example, +expose `InvoiceSender`, `ReportBuilder`, or `CatalogImporter` from Yii and call that service from the host application. + +## Keep boundaries explicit + +Avoid mixing request lifecycles. Let the host application continue to own its HTTP request and response. Let Yii provide +services that do not assume Yii is handling the current request. + +Good candidates for reuse: + +- domain services; +- repositories and database connections; +- mailers and notification services; +- loggers; +- validators; +- queue producers; +- command-like application services. + +Avoid pulling in Yii actions, middleware stacks, sessions, CSRF middleware, or view rendering unless the host application +explicitly delegates that whole responsibility to Yii. + +## Configuration groups + +The default application template separates configuration by group: + +- `di` is shared by web and console entry points; +- `di-console` is console-specific and includes `di` in the template; +- `di-web` is web-specific and includes `di`; +- `params-console` and `params-web` extend common `params`. + +Choose the smallest group that contains the services you need. If the host application only needs domain services, keep +those definitions in `config/common/di/*.php` so both Yii and the third-party app can use them without web-only +dependencies. + +After changing `config/configuration.php`, rebuild the merge plan: + +```shell +composer yii-config-rebuild +``` + +## Error handling and logging + +The host application should remain responsible for top-level error handling. Catch exceptions at the integration +boundary when the host app needs to convert them into its own response or error format. + +Yii services can still use `Psr\Log\LoggerInterface`. Configure the Yii logger to write to the same destination as the +host application or bridge both applications to the same PSR-3 logger. + +## Long-running host processes + +If the third-party application is a worker, daemon, or event-loop server, avoid mutable shared state in services. Yii +services resolved from the container are shared by default, so design them as stateless services or create a fresh +container for each isolated job when stateful dependencies are unavoidable.