diff --git a/.vale.ini b/.vale.ini index 2b630a0c..a5a1293a 100644 --- a/.vale.ini +++ b/.vale.ini @@ -3,3 +3,6 @@ MinAlertLevel = suggestion [*.md] BasedOnStyles = Microsoft +Microsoft.Acronyms = NO +Microsoft.Headings = NO +Microsoft.HeadingAcronyms = NO diff --git a/src/cookbook/configuring-webservers/apache.md b/src/cookbook/configuring-webservers/apache.md index 5e82c8d5..af5a1405 100644 --- a/src/cookbook/configuring-webservers/apache.md +++ b/src/cookbook/configuring-webservers/apache.md @@ -51,5 +51,7 @@ SetEnv APP_ENV dev # ...other settings... ``` -In the above, note the usage of `SetEnv`. Since the Yii3 application template is using environment variables, this is a possible +In the above, note the usage of `SetEnv`. Since Yii3 application templates use environment variables, this is a possible place to set them. In production environment remember to set `APP_ENV` to `prod`. + +See [application logs](general.md#application-logs) for logging configuration. diff --git a/src/cookbook/configuring-webservers/general.md b/src/cookbook/configuring-webservers/general.md index 21337bea..17fc88a5 100644 --- a/src/cookbook/configuring-webservers/general.md +++ b/src/cookbook/configuring-webservers/general.md @@ -7,6 +7,27 @@ Point the document root of your web server to the `app/public` folder. > If you're running your Yii application behind a reverse proxy, you might need to configure > [Trusted proxies and headers](../../guide/security/trusted-request.md). +## Application logs + +Yii3 application templates write application logs to standard output (`stdout`, or `php://stdout`) by default. +They don't create application log files. Standard error (`stderr`) requires explicit log target configuration. +Docker collects container output, but on a server without containers you must configure where that output goes +or [configure a file target](../../guide/runtime/logging.md#logging-to-files). +Web server access and error log settings don't configure Yii's log targets. + +### PHP-FPM + +If your web server uses PHP-FPM, enable worker output capture in the application's PHP-FPM pool configuration: + +```ini +catch_workers_output = yes +``` + +Reload PHP-FPM after changing its configuration. PHP-FPM sends worker standard output and standard error to its +main error log. The `error_log` directive in `php-fpm.conf` sets the destination. +Without this setting, PHP-FPM redirects both streams to `/dev/null` by default. +See the [PHP-FPM configuration reference](https://www.php.net/manual/en/install.fpm.configuration.php). + ## Specific server configurations - [Nginx](nginx.md) diff --git a/src/cookbook/configuring-webservers/iis.md b/src/cookbook/configuring-webservers/iis.md index 4217dbbc..6cb5625a 100644 --- a/src/cookbook/configuring-webservers/iis.md +++ b/src/cookbook/configuring-webservers/iis.md @@ -29,3 +29,5 @@ Use the following content: ``` Also, [IIS documentation](https://learn.microsoft.com/en-us/iis/) could be useful to configure PHP on IIS. + +See [application logs](general.md#application-logs) for logging configuration. diff --git a/src/cookbook/configuring-webservers/lighttpd.md b/src/cookbook/configuring-webservers/lighttpd.md index 551300c6..f5549624 100644 --- a/src/cookbook/configuring-webservers/lighttpd.md +++ b/src/cookbook/configuring-webservers/lighttpd.md @@ -5,3 +5,5 @@ To use [lighttpd](https://www.lighttpd.net/) >= 1.4.24, put `index.php` in the w ``` url.rewrite-if-not-file = ("(.*)" => "/index.php/$0") ``` + +See [application logs](general.md#application-logs) for logging configuration. diff --git a/src/cookbook/configuring-webservers/nginx-unit.md b/src/cookbook/configuring-webservers/nginx-unit.md index 3c736cea..04ca5c27 100644 --- a/src/cookbook/configuring-webservers/nginx-unit.md +++ b/src/cookbook/configuring-webservers/nginx-unit.md @@ -60,5 +60,7 @@ Here is a sample configuration. You can also [set up](https://unit.nginx.org/configuration/#php) your PHP environment or supply a custom `php.ini` in the same configuration. -Since the Yii3 application template uses environment variables, you can set them in `applications.yii.environment`. +Since Yii3 application templates use environment variables, you can set them in `applications.yii.environment`. In a production environment, remember to set `APP_ENV` to `prod`. + +See [application logs](general.md#application-logs) for logging configuration. diff --git a/src/cookbook/configuring-webservers/nginx.md b/src/cookbook/configuring-webservers/nginx.md index 52ec9c31..3ca26cb4 100644 --- a/src/cookbook/configuring-webservers/nginx.md +++ b/src/cookbook/configuring-webservers/nginx.md @@ -56,5 +56,8 @@ to avoid many unnecessary system `stat()` calls. Also, note that when running an HTTPS server, you need to add `fastcgi_param HTTPS on;` so that Yii can detect if a connection is secure. -In the above, note the usage of `fastcgi_param APP_ENV`. Since the Yii3 application template is using environment variables, +In the above, note the usage of `fastcgi_param APP_ENV`. Since Yii3 application templates use environment variables, this is a possible place to set them. In production environment remember to set `APP_ENV` to `prod`. + +The Nginx `access_log` and `error_log` directives above don't capture PHP-FPM worker output. +See [application logs](general.md#application-logs) for logging configuration. diff --git a/src/guide/runtime/logging.md b/src/guide/runtime/logging.md index c53f76cc..02e2a17d 100644 --- a/src/guide/runtime/logging.md +++ b/src/guide/runtime/logging.md @@ -15,6 +15,23 @@ Using the Yii logging framework involves the following steps: In this section, the focus in on the first two steps. +## Default log destination + +Yii3 application templates +([web](https://github.com/yiisoft/app/blob/master/config/common/di/logger.php) and +[API](https://github.com/yiisoft/app-api/blob/master/config/common/di/logger.php)) +configure `Yiisoft\Log\StreamTarget`, which writes to standard output (`stdout`, or `php://stdout`) by default. +They don't create application log files, such as `runtime/logs/app.log`. +`StreamTarget` also supports standard error (`stderr`, or `php://stderr`), but you must configure it explicitly. + +This works well with Docker, which [collects container output](https://docs.docker.com/engine/logging/). +Use `docker logs ` to read it when the container's logging driver supports that command. + +Without containers, the destination depends on how you start PHP and capture its output. +For example, PHP-FPM discards worker output by default unless you enable `catch_workers_output`. +See [web server logging configuration](../../cookbook/configuring-webservers/general.md#application-logs). +To have Yii write application log files directly, configure a [file target](#logging-to-files). + ## Log Messages To record log messages, you need an instance of PSR-3 logger. @@ -130,8 +147,65 @@ learn how to configure and use them. * [[\Yiisoft\Log\Target\File\FileTarget]]: saves log messages in files. * [[\Yiisoft\Log\Target\Syslog\SyslogTarget]]: saves log messages to syslog by calling the PHP function `syslog()`. -In the following, we will describe the features common to all log targets. +### Logging to files + +To write application logs to a file, install the file target package: + +```shell +composer require yiisoft/log-target-file +``` + +In your application's `config/common/di/logger.php`, replace the `StreamTarget` reference with `FileTarget`: +```php +use Psr\Log\LoggerInterface; +use Yiisoft\Definitions\ReferencesArray; +use Yiisoft\Log\Logger; +use Yiisoft\Log\Target\File\FileTarget; + +return [ + LoggerInterface::class => [ + 'class' => Logger::class, + '__construct()' => [ + 'targets' => ReferencesArray::from([ + FileTarget::class, + ]), + ], + ], +]; +``` + +The package's default configuration writes to `@runtime/logs/app.log` and enables log rotation. +To change the path, set `$params['yiisoft/log-target-file']['fileTarget']['file']` in `config/common/params.php`. +Ensure that the PHP process can write to the log directory, and keep it outside the web server's document root. + +The file target package's default configuration also filters out `alert`, `critical`, and `notice` messages. +The templates' `StreamTarget` accepts all eight log levels. To keep that behavior, add the following entry to the +array that `config/common/params.php` returns: + +```php +use Psr\Log\LogLevel; + +return [ + // Other application parameters... + 'yiisoft/log-target-file' => [ + 'fileTarget' => [ + 'levels' => [ + LogLevel::EMERGENCY, + LogLevel::ALERT, + LogLevel::CRITICAL, + LogLevel::ERROR, + LogLevel::WARNING, + LogLevel::NOTICE, + LogLevel::INFO, + LogLevel::DEBUG, + ], + ], + ], +]; +``` + +In the following, we will describe the features common to all log targets. ### Message Filtering