Update getting started according to new app template #239
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
samdark
changed the title
samdark
requested review from
Tigrov,
arogachev,
darkdef,
roxblnfk,
rustamwin,
terabytesoftw,
viktorprogger,
vjik and
xepozz
Tigrov
reviewed
Aug 30, 2025
Co-authored-by: Sergei Tigrov <[email protected]>
diff --git c/014-docs.md i/014-docs.md index be7c563..53bfd77 100644 --- c/014-docs.md +++ i/014-docs.md @@ -25,26 +25,37 @@ The guide should follow [Micosoft style guide](https://learn.microsoft.com/en-us ## Blocks -Blocks use the Markdown `> Type: `. There are four block types: +Blocks are in the [GitHub Alerts format](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts): -* `Warning`, for bad security things and other problems -* `Note`, to emphasize key concepts, things to avoid -* `Info`, general information (an aside); not as strong as a "Note" -* `Tip`, pro tips, extras. It can be useful but may not be needed by everyone all the time +``` +> [!NOTE] +> Useful information that users should know, even when skimming content. -The sentence after the colon should begin with a capital letter. +> [!TIP] +> Helpful advice for doing things better or more easily. + +> [!IMPORTANT] +> Key information users need to know to achieve their goal. + +> [!WARNING] +> Urgent info that needs immediate user attention to avoid problems. + +> [!CAUTION] +> Advises about risks or negative outcomes of certain actions. +``` When translating documentation, these Block indicators should not be translated. Keeps them intact as they are and only translate the block content. -For translating the `Type` word, each guide translation should have a `blocktypes.json` file +For translating the label for the block, each guide translation should have a `blocktypes.json` file containing the translations. The following shows an example for German: ```json { - "Warning:": "Achtung:", - "Note:": "Hinweis:", - "Info:": "Info:", - "Tip:": "Tipp:" + "Note": "Hinweis", + "Tip": "Tipp", + "Important": "Wichtig", + "Warning": "Achtung", + "Caution": "Vorsicht" } ``` diff --git c/015-phpstorm.md i/015-phpstorm.md index 11b63c3..02ed582 100644 --- c/015-phpstorm.md +++ i/015-phpstorm.md @@ -12,7 +12,8 @@ We use the following set of coding styles for metadata. - Metadata should be placed in `/.phpstorm.meta.php` directory. - Configuration should be split into files. Each file should be named after a class it configures. -> Note: There is no support for subdirectories in PhpStorm yet. +> [!NOTE] +> There is no support for subdirectories in PhpStorm yet. ### Constants diff --git c/cookbook/en/configuring-webservers/general.md i/cookbook/en/configuring-webservers/general.md index 50c239f..f139b5d 100644 --- c/cookbook/en/configuring-webservers/general.md +++ i/cookbook/en/configuring-webservers/general.md @@ -3,7 +3,8 @@ On a production server, if you don't use Docker, configure your web server to serve only the application's public files. Point the document root of your web server to the `app/public` folder. -> Note: If you're running your Yii application behind a reverse proxy, you might need to configure +> [!IMPORTANT] +> If you're running your Yii application behind a reverse proxy, you might need to configure > [Trusted proxies and headers](../../../guide/en/security/trusted-request.md). ## Specific server configurations diff --git c/guide/en/caching/data.md i/guide/en/caching/data.md index 77cf378..dcd396c 100644 --- c/guide/en/caching/data.md +++ i/guide/en/caching/data.md @@ -59,7 +59,8 @@ Yii provides the following handlers: [You could find more handlers at packagist.org](https://packagist.org/providers/psr/simple-cache-implementation). -> Tip: You may use different cache storage in the same application. A common strategy is: +> [!TIP] +> You may use different cache storage in the same application. A common strategy is: > - To use memory-based cache storage to store small but constantly used data (e.g., statistics) > - To use file-based or database-based cache storage to store big and less often used data (e.g., page content) diff --git c/guide/en/concept/aliases.md i/guide/en/concept/aliases.md index 8294b01..7ae9e8d 100644 --- c/guide/en/concept/aliases.md +++ i/guide/en/concept/aliases.md @@ -32,7 +32,8 @@ return [ ]; ``` -> Note: The file path or URL being aliased may *not* necessarily refer to an existing file or resource. +> [!NOTE] +> The file path or URL being aliased may *not* necessarily refer to an existing file or resource. Given a defined alias, you may derive a new alias by appending a slash `/` followed with one or more path segments. For example, `@foo` is a root alias, while `@foo/bar/file.php` is a derived alias. @@ -94,7 +95,8 @@ public function actionIndex(Aliases $aliases) The path/URL represented by a derived alias is determined by replacing the root alias part with its corresponding path/URL in the derived alias. -> Note: The `get()` method doesn't check whether the resulting path/URL refers to an existing file or resource. +> [!NOTE] +> The `get()` method doesn't check whether the resulting path/URL refers to an existing file or resource. A root alias may also contain slash `/` characters. The `get()` method diff --git c/guide/en/concept/configuration.md i/guide/en/concept/configuration.md index 1a6c1e3..b5307fe 100644 --- c/guide/en/concept/configuration.md +++ i/guide/en/concept/configuration.md @@ -266,7 +266,8 @@ Read more about it in ["Events"](events.md). Parameters, `config/params.php` store configuration values that are used in other config files to configuring services and service providers. -> Tip: Don't use parameters, constants or environment variables directly in your application, configure +> [!TIP] +> Don't use parameters, constants or environment variables directly in your application, configure > services instead. Default application `params.php` looks like the following: diff --git c/guide/en/runtime/logging.md i/guide/en/runtime/logging.md index 8c91558..90b60b9 100644 --- c/guide/en/runtime/logging.md +++ i/guide/en/runtime/logging.md @@ -81,7 +81,8 @@ the constant appears. For example, it's equal to the string `'App\\Service\\MyService::serve'` if the above line of code is called within this method. -> Info: The logging methods described above are actually shortcuts to the [[\Psr\Log\LoggerInterface::log()]]. +> [!IMPORTANT] +> The logging methods described above are actually shortcuts to the [[\Psr\Log\LoggerInterface::log()]]. Note that PSR-3 package provides `\Psr\Log\NullLogger` class that provides the same set of methods but doesn't log anything. That means that you don't have to check if logger is configured with `if ($logger !== null)` and, instead, @@ -267,7 +268,8 @@ $logger = new \Yiisoft\Log\Logger($targets); $logger->setExcludedTracePaths(['/path/to/file', '/path/to/folder']); ``` -> Info: Getting call stack information isn't trivial. Therefore, you should only use this feature during development +> [!IMPORTANT] +> Getting call stack information isn't trivial. Therefore, you should only use this feature during development or when debugging an application. @@ -284,7 +286,8 @@ $logger = new \Yiisoft\Log\Logger($targets); $logger->setFlushInterval(100); // default is 1000 ``` -> Info: Message flushing also occurs when the application ends, +> [!IMPORTANT] +> Message flushing also occurs when the application ends, which ensures log targets can receive complete log messages. When the [[\Yiisoft\Log\Logger|logger object]] flushes log messages to [log targets](#log-targets), @@ -311,7 +314,8 @@ $logger = new \Yiisoft\Log\Logger([$fileTarget]); $logger->setFlushInterval(1); ``` -> Note: Frequent message flushing and exporting will degrade the performance of your application. +> [!NOTE] +> Frequent message flushing and exporting will degrade the performance of your application. ### Toggling log targets <span id="toggling-log-targets"></span> @@ -350,7 +354,8 @@ The following protected methods will also be available for child targets: For more details, you may refer to any of the log target classes included in the package. -> Tip: Instead of creating your own loggers, you may try any PSR-3 compatible logger such +> [!TIP] +> Instead of creating your own loggers, you may try any PSR-3 compatible logger such as [Monolog](https://github.com/Seldaek/monolog) by using [[\Yii\Log\PsrTarget]]. ```php diff --git c/guide/en/runtime/routing.md i/guide/en/runtime/routing.md index 47bf8ba..34dffb4 100644 --- c/guide/en/runtime/routing.md +++ i/guide/en/runtime/routing.md @@ -261,7 +261,8 @@ of `{ParamName:RegExp}`, where `ParamName` specifies the parameter name and `Reg expression used to match parameter values. If `RegExp` isn't specified, it means the parameter value should be a string without any slash. -> Note: You can only use regular expressions inside parameters. The rest of the pattern is considered plain text. +> [!NOTE] +> You can only use regular expressions inside parameters. The rest of the pattern is considered plain text. You can't use capturing groups. For example `{lang:(en|de)}` isn't a valid placeholder, because `()` is a capturing group. Instead, you can use either `{lang:en|de}` or `{lang:(?:en|de)}`. diff --git c/guide/en/runtime/sessions.md i/guide/en/runtime/sessions.md index 7b83c03..351ef0c 100644 --- c/guide/en/runtime/sessions.md +++ i/guide/en/runtime/sessions.md @@ -72,7 +72,8 @@ public function actionProfile(\Yiisoft\Session\SessionInterface $session) } ``` -> Note: Closing session as early as possible is a good practice since many session implementations are blocking other +> [!NOTE] +> Closing session as early as possible is a good practice since many session implementations are blocking other > requests while the session is open. There are two more ways to close a session: diff --git c/guide/en/start/creating-project.md i/guide/en/start/creating-project.md index 7e691e7..4ce03e0 100644 --- c/guide/en/start/creating-project.md +++ i/guide/en/start/creating-project.md @@ -16,18 +16,22 @@ docker run --rm -it -v "$(pwd):/app" composer/composer create-project yiisoft/ap This installs the latest stable version of the Yii project template in a directory named `your_project`. You can choose a different directory name if you want. -> Tip: If you want to install the latest development version of Yii, you may use the following command instead, +> [!IMPORTANT] +> If you want to install the latest development version of Yii, you may use the following command instead, > which adds a [stability option](https://getcomposer.org/doc/04-schema.md#minimum-stability): > > ```bash > docker run --rm -it -v "$(pwd):/app" composer/composer create-project --stability=dev yiisoft/app your_project > ``` -> -> Note: Don't use the development version of Yii for production because it may break your running code. + + +> [!NOTE] +> Don't use the development version of Yii for production because it may break your running code. After you finish installation, run `make up` and open your browser to the URL `http://localhost/`. -> Note: By default, the HTTP server listens on port 80. If that port is already in use, or you want to -serve many applications this way, specify the port via `DEV_PORT` in the `docker/.env` file. +> [!NOTE] +> By default, the HTTP server listens on port 80. If that port is already in use, or you want to +> serve many applications this way, specify the port via `DEV_PORT` in the `docker/.env` file.  diff --git c/guide/en/structure/domain.md i/guide/en/structure/domain.md index 56580b1..a751005 100644 --- c/guide/en/structure/domain.md +++ i/guide/en/structure/domain.md @@ -5,7 +5,8 @@ in mind (the problem context), you build an abstraction that consists of entitie operates these entities. To focus on the complex part of the problem, domain is, ideally, separated from the infrastructure part of the system (that's how to save data into a database, how to form HTTP response, etc.). -> Note: Such isolation is suitable for complex systems. If your project domain is basically create/read/update/delete +> [!NOTE] +> Such isolation is suitable for complex systems. If your project domain is basically create/read/update/delete > for a set of records with not much complex logic, it makes no sense to apply a complex solution to a simple problem. > The individual concepts of domain design below could be applied separately, so make sure to check these even if your > project isn't that complicated. diff --git c/guide/en/structure/package.md i/guide/en/structure/package.md index 29f889a..2089c68 100644 --- c/guide/en/structure/package.md +++ i/guide/en/structure/package.md @@ -14,7 +14,8 @@ to use it. This is useful if you're developing private packages that you want to Packages installed by Composer are stored in the `vendor` directory of your project. Because the Composer is a dependency manager, when it installs a package, it will also install all its dependent packages. -> Warning: `vendor` directory of your application should never be modified. +> [!WARNING] +> `vendor` directory of your application should never be modified. A package could be installed with the following command: @@ -130,7 +131,8 @@ Each Composer package should have a package name which uniquely identifies the p The format of package names is `vendorName/projectName`. For example, in the package name `yiisoft/queue`, the vendor name, and the project name are `yiisoft` and `queue`, respectively. -> Warning: Don't use `yiisoft` as your vendor name as it's reserved for use by the Yii itself. +> [!WARNING] +> Don't use `yiisoft` as your vendor name as it's reserved for use by the Yii itself. We recommend you prefix `yii-` to the project name for packages that aren't able to work as general PHP packages and require Yii application. This will allow users to more easily tell whether a package is Yii specific. diff --git c/guide/es/runtime/logging.md i/guide/es/runtime/logging.md index 59e80d7..9b8fdd8 100644 --- c/guide/es/runtime/logging.md +++ i/guide/es/runtime/logging.md @@ -75,7 +75,8 @@ The `__METHOD__` constant evaluates as the name of the method (prefixed with the the constant appears. For example, it is equal to the string `'App\\Service\\MyService::serve'` if the above line of code is called within this method. -> Info: The logging methods described above are actually shortcuts to the [[\Psr\Log\LoggerInterface::log()]]. +> [!IMPORTANT] +> The logging methods described above are actually shortcuts to the [[\Psr\Log\LoggerInterface::log()]]. Note that PSR-3 package provides `\Psr\Log\NullLogger` class that provides the same set of methods but does not log anything. That means that you don't have to check if logger is configured with `if ($logger !== null)` and, instead, @@ -211,7 +212,8 @@ $logger->setTraceLevel(3); The above application configuration sets trace level to be 3 so each log message will be appended with at most 3 levels of the call stack at which the log message is recorded. -> Info: Getting call stack information is not trivial. Therefore, you should only use this feature during development +> [!IMPORTANT] +> Getting call stack information is not trivial. Therefore, you should only use this feature during development or when debugging an application. @@ -228,7 +230,8 @@ $logger = new \Yiisoft\Log\Logger($targets); $logger->setFlushInterval(100); // default is 1000 ``` -> Info: Message flushing also occurs when the application ends, which ensures log targets can receive complete log messages. +> [!IMPORTANT] +> Message flushing also occurs when the application ends, which ensures log targets can receive complete log messages. When the [[\Yiisoft\Log\Logger|logger object]] flushes log messages to [log targets](#log-targets), they do not get exported immediately. Instead, the message exporting only occurs when a log target accumulates certain number of the filtered @@ -253,7 +256,8 @@ $logger = new \Yiisoft\Log\Logger([$fileTarget]); $logger->setFlushInterval(1); ``` -> Note: Frequent message flushing and exporting will degrade the performance of your application. +> [!NOTE] +> Frequent message flushing and exporting will degrade the performance of your application. ### Toggling Log Targets <span id="toggling-log-targets"></span> @@ -281,5 +285,6 @@ sending the content of the [[\Yii\Log\Target::messages]] array to a designated m [[\Yii\Log\Target::formatMessage()]] method to format each message. For more details, you may refer to any of the log target classes included in the Yii release. -> Tip: Instead of creating your own loggers you may try any PSR-3 compatible logger such +> [!TIP] +> Instead of creating your own loggers you may try any PSR-3 compatible logger such as [Monolog](https://github.com/Seldaek/monolog) by using [[\Yii\Log\PsrTarget]]. diff --git c/guide/es/runtime/sessions.md i/guide/es/runtime/sessions.md index bb738b7..d5e5f6c 100644 --- c/guide/es/runtime/sessions.md +++ i/guide/es/runtime/sessions.md @@ -23,8 +23,9 @@ public function actionProfile(\Yiisoft\Yii\Web\Session\SessionInterface $session } ``` -> Note: Closing session as early as possible is a good practice since many session implementations are blocking other -> requests while session is open. +> [!NOTE] +> Closing session as early as possible is a good practice since many session implementations are blocking other +> requests while the session is open. There are two more ways to close session: diff --git c/guide/es/start/hello.md i/guide/es/start/hello.md index 2849abc..ed15c64 100644 --- c/guide/es/start/hello.md +++ i/guide/es/start/hello.md @@ -1,6 +1,7 @@ # Saying Hello -> Note: This document reflects current configuration. Yii team is going to make it significantly simpler before release. +> [!NOTE] +> This document reflects the current configuration. Yii team is going to make it significantly simpler before release. This section describes how to create a new "Hello" page in your application. To achieve this goal, you will define a route, create [a handler](../structure/handler.md) diff --git c/guide/es/start/installation.md i/guide/es/start/installation.md index 930d64a..d7c27d0 100644 --- c/guide/es/start/installation.md +++ i/guide/es/start/installation.md @@ -42,7 +42,8 @@ composer create-project yiisoft/yii-demo app This will install the latest stable version of Yii application template in a directory named `app`. You can choose a different directory name if you want. -> Tip: If you want to install the latest development version of Yii, you may use the following command instead, +> [!TIP] +> If you want to install the latest development version of Yii, you may use the following command instead, > which adds a [stability option](https://getcomposer.org/doc/04-schema.md#minimum-stability): > > ```bash @@ -71,7 +72,8 @@ console command while in the project `public` directory: ../vendor/bin/yii serve ``` -> Note: By default, the HTTP-server will listen to port 8080. However, if that port is already in use or you wish to +> [!NOTE] +> By default, the HTTP-server will listen to port 8080. However, if that port is already in use or you wish to serve multiple applications this way, you might want to specify what port to use. Just add the --port argument: ```bash @@ -91,8 +93,9 @@ You should see the above "Congratulations!" page in your browser. ## Configuring Web Servers <span id="configuring-web-servers"></span> -> Info: You may skip this subsection for now if you are just test-driving Yii with no intention - of deploying it to a production server. +> [!IMPORTANT] +> You may skip this subsection for now if you are just test-driving Yii with no intention +> of deploying it to a production server. The application installed according to the above instructions should work out of the box with either an [Apache HTTP server](https://httpd.apache.org/) or an [Nginx HTTP server](https://nginx.org/), on @@ -104,15 +107,18 @@ requires pointing the document root of your Web server to the `app/public` folde want to hide `index.php` from the URL, as described in the [Routing and URL Creation](runtime-routing.md) section. In this subsection, you'll learn how to configure your Apache or Nginx server to achieve these goals. -> Info: By setting `app/public` as the document root, you also prevent end users from accessing +> [!IMPORTANT] +> By setting `app/public` as the document root, you also prevent end users from accessing your private application code and sensitive data files that are stored in the sibling directories of `app/public`. Denying access to those other folders is a security improvement. -> Info: If your application will run in a shared hosting environment where you do not have permission +> [!IMPORTANT] +> If your application runs in a shared hosting environment where you do not have permission to modify its Web server configuration, you may still adjust the structure of your application for better security. Please refer to the [Shared Hosting Environment](tutorial-shared-hosting.md) section for more details. -> Info: If you are running your Yii application behind a reverse proxy, you might need to configure +> [!IMPORTANT] +> If you are running your Yii application behind a reverse proxy, you might need to configure > [Trusted proxies and headers](runtime-requests.md#trusted-proxies) in the request component. ### Apache <span id="apache"></span> diff --git c/guide/es/start/workflow.md i/guide/es/start/workflow.md index c1c7797..c4fb91d 100644 --- c/guide/es/start/workflow.md +++ i/guide/es/start/workflow.md @@ -4,7 +4,8 @@ After installing Yii, you have a working Yii application that can be accessed vi the URL `http://hostname/`. This section will introduce the application's built-in functionality, how the code is organized, and how the application handles requests in general. -> Info: For simplicity, throughout this "Getting Started" tutorial, it's assumed that you have set `app/public` +> [!IMPORTANT] +> For simplicity, throughout this "Getting Started" tutorial, it's assumed that you have set `app/public` as the document root of your Web server, and configured the URL for accessing your application to be `http://hostname/index.php` or something similar. For your needs, please adjust the URLs in our descriptions accordingly. diff --git c/guide/es/structure/domain.md i/guide/es/structure/domain.md index f1b5f20..e7703a3 100644 --- c/guide/es/structure/domain.md +++ i/guide/es/structure/domain.md @@ -5,7 +5,8 @@ in mind (the problem context), we build an abstraction that consists of entities operates these entities. To focus on the complex part of the problem, domain is, ideally, separated from infrastructure part of the system (i.e., how to save data into database, how to form HTTP response etc.). -> Note: Such isolation is suitable for complex systems. If your project domain is basically create/read/update/delete +> [!NOTE] +> Such isolation is suitable for complex systems. If your project domain is basically create/read/update/delete > for a set of records with not much complex logic it makes no sense to apply complex solution to a simple problem. > Individual concepts of domain design below could be applied separately so make sure to check these even if your > project isn't that complicated. diff --git c/guide/es/structure/package.md i/guide/es/structure/package.md index b19c9e6..9b64000 100644 --- c/guide/es/structure/package.md +++ i/guide/es/structure/package.md @@ -14,7 +14,8 @@ to use it. This is useful if you are developing private packages that you want t Packages installed by Composer are stored in the `vendor` directory of your project. Because Composer is a dependency manager, when it installs a package, it will also install all its dependent packages. -> Warning: `vendor` directory of your application should never be modified. +> [!WARNING] +> `vendor` directory of your application should never be modified. A package could be installed with the following command: @@ -113,7 +114,8 @@ Each Composer package should have a package name which uniquely identifies the p The format of package names is `vendorName/projectName`. For example, in the package name `yiisoft/queue`, the vendor name and the project name are `yiisoft` and `queue`, respectively. -> Warning: Do NOT use `yiisoft` as your vendor name as it is reserved for use by the Yii itself. +> [!WARNING] +> Do NOT use `yiisoft` as your vendor name as it is reserved for use by the Yii itself. We recommend you prefix `yii-` to the project name for packages that are not able to work as general PHP packages and require Yii application. This will allow users to more easily tell whether a package is Yii specific.
Tigrov
reviewed
Aug 30, 2025
vjik
reviewed
Aug 31, 2025
Co-authored-by: Sergei Predvoditelev <[email protected]>
Co-authored-by: Sergei Predvoditelev <[email protected]>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
No description provided.