Fix docs (#260)

Co-authored-by: Sergei Predvoditelev <[email protected]>
yiisoft · May 18, 2024 · e454355 · e454355
1 parent e0d7405
commit e454355
Show file tree

Hide file tree

Showing 9 changed files with 185 additions and 33 deletions.
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 <p align="center">
     <a href="https://github.com/yiisoft" target="_blank">
-        <img src="https://yiisoft.github.io/docs/images/yii_logo.svg" height="100px">
+        <img src="https://yiisoft.github.io/docs/images/yii_logo.svg" height="100px" alt="Yii">
     </a>
     <h1 align="center">Yii View Rendering Library</h1>
     <br>
@@ -23,7 +23,7 @@ PHP-based as default, and more. It's used in [Yii Framework](https://www.yiifram
 
 ## Installation
 
-The package could be installed via composer:
+The package could be installed with [Composer](https://getcomposer.org):
 
 ```shell
 composer require yiisoft/view
@@ -33,8 +33,8 @@ composer require yiisoft/view
 
 The package provides two use cases for managing view templates:
 
-- [Basic functionality](docs/basic-functionality.md) for use in any environment.
-- Advanced functionality for [use in a web environment](docs/use-in-web-environment.md).
+- [Basic functionality](docs/guide/en/basic-functionality.md) for use in any environment.
+- Advanced functionality for [use in a web environment](docs/guide/en/use-in-web-environment.md).
 
 ### State of `View` and `WebView` services
 
@@ -116,7 +116,7 @@ final class LocaleMiddleware implements MiddlewareInterface
         ...
     }
 }
-````
+```
 
 Example with immutable method:
 
@@ -143,38 +143,19 @@ $view = $view->withClearedState();
 ## Extensions
 
 - [yiisoft/yii-view](https://github.com/yiisoft/yii-view) - a wrapper that's used in
-  [Yii Framework]((https://www.yiiframework.com/)).
+  [Yii Framework](https://www.yiiframework.com/).
   Adds extra functionality for a web environment and compatibility 
   with [PSR-7](https://www.php-fig.org/psr/psr-7) interfaces.
 - [yiisoft/view-twig](https://github.com/yiisoft/view-twig) - an extension that provides a view renderer that will
   allow you to use the [Twig](https://twig.symfony.com) view template engine, instead of the default PHP renderer.
 
-## Testing
-
-### Unit testing
-
-The package is tested with [PHPUnit](https://phpunit.de/). To run tests:
-
-```shell
-./vendor/bin/phpunit
-```
-
-### Mutation testing
+## Documentation
 
-The package tests are checked with [Infection](https://infection.github.io/) mutation framework with
-[Infection Static Analysis Plugin](https://github.com/Roave/infection-static-analysis-plugin). To run it:
+- Guide: [English](docs/guide/en/README.md), [Português - Brasil](docs/guide/pt-BR/README.md)
+- [Internals](docs/internals.md)
 
-```shell
-./vendor/bin/roave-infection-static-analysis-plugin
-```
-
-### Static analysis
-
-The code is statically analyzed with [Psalm](https://psalm.dev/). To run static analysis:
-
-```shell
-./vendor/bin/psalm
-```
+If you need help or have a question, the [Yii Forum](https://forum.yiiframework.com/c/yii-3-0/63) is a good place for that.
+You may also check out other [Yii Community Resources](https://www.yiiframework.com/community).
 
 ## License
 

diff --git a/composer.json b/composer.json
@@ -9,12 +9,12 @@
     "homepage": "https://www.yiiframework.com/",
     "license": "BSD-3-Clause",
     "support": {
+        "issues": "https://github.com/yiisoft/view/issues?state=open",
         "source": "https://github.com/yiisoft/view",
-        "issues": "https://github.com/yiisoft/view/issues",
         "forum": "https://www.yiiframework.com/forum/",
         "wiki": "https://www.yiiframework.com/wiki/",
-        "chat": "https://t.me/yii3en",
-        "irc": "ircs://irc.libera.chat:6697/yii"
+        "irc": "ircs://irc.libera.chat:6697/yii",
+        "chat": "https://t.me/yii3en"
     },
     "funding": [
         {

diff --git a/docs/guide/en/README.md b/docs/guide/en/README.md
@@ -0,0 +1,6 @@
+# Yii View
+
+The package provides two use cases for managing view templates:
+
+- [Basic functionality](basic-functionality.md) for use in any environment.
+- [Advanced functionality](use-in-web-environment.md) for use in a web environment.
diff --git a/docs/guides/en/basic-functionality.md → docs/guide/en/basic-functionality.md b/docs/guides/en/basic-functionality.md → docs/guide/en/basic-functionality.md
diff --git a/docs/guides/en/use-in-web-environment.md → docs/guide/en/use-in-web-environment.md b/docs/guides/en/use-in-web-environment.md → docs/guide/en/use-in-web-environment.md
diff --git a/docs/guide/pt-BR/README.md b/docs/guide/pt-BR/README.md
@@ -0,0 +1,121 @@
+## Uso geral
+
+O pacote fornece dois casos de uso para gerenciamento de modelos de visualização:
+
+- [Funcionalidade básica](basic-functionality.md) para uso em qualquer ambiente.
+- [Funcionalidade avançada](use-in-web-environment.md) para uso em ambiente web.
+
+### Estado dos serviços `View` e `WebView`
+
+Embora sejam imutáveis e, por si só, sem estado, os serviços `View` e `WebView` possuem conjuntos de serviços com estado e dados mutáveis.
+
+Serviço `View`:
+- parâmetros,
+- blocos,
+- tema,
+- local.
+
+Serviço `WebView`:
+- parâmetros,
+- blocos,
+- tema,
+- localidade,
+- título,
+- meta tags e links,
+- strings JS/CSS,
+- Arquivos JS/CSS.
+
+O estado de `View` e `WebView` não são clonados quando os serviços são clonados. Então quando
+usar com `with*()`, instâncias novas e antigas compartilharão o mesmo conjunto de dados mutáveis com estado. Permitem, por exemplo,
+obter `WebView` por meio de dicas de tipo em um controlador e alterar o caminho do contexto:
+
+```php
+final class BlogController {
+    private WebView $view;
+    public function __construct (WebView $view) {
+        $this->view = $view->withContextPath(__DIR__.'/views');
+    }
+}
+```
+
+e então registrar CSS em um widget:
+
+```php
+final class LastPosts extends Widget 
+{    
+    private WebView $view;
+    public function __construct (WebView $view) {
+        $this->view = $view;
+    }
+    protected function run(): string
+    {
+        ...
+        $this->view->registerCss('.lastPosts { background: #f1f1f1; }');
+        ...
+    }
+}
+```
+
+#### Estado Locale (internacionalização)
+
+Você pode alterar a localidade usando `setLocale()`, que será aplicado a todas as outras instâncias que usaram o estado atual
+incluindo os existentes. Se você precisar alterar a localidade apenas para uma única instância, poderá usar o método imutável
+`withLocale()`. A localidade será aplicada a todas as visualizações renderizadas nas visualizações com chamadas `render()`.
+
+Exemplo com método mutável:
+
+```php
+final class LocaleMiddleware implements MiddlewareInterface
+{    
+    ...
+    private WebView $view;
+    ...
+    public function __construct (
+        ...
+        WebView $view
+        ...
+    ) {
+        $this->view = $view;
+    }
+
+    public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
+    {
+        ...
+        $this->view->setLocale($locale);
+        ...
+    }
+}
+```
+
+Exemplo com método imutável:
+
+```php
+final class BlogController {
+
+    private WebView $view;
+
+    public function __construct (WebView $view) {
+        $this->view = $view;
+    }
+
+    public function index() {
+        return $this->view->withLocale('es')->render('index');
+    }
+}
+```
+
+#### Redefinir o estado
+
+Para obter um `View` ou `WebView` clonado profundamente, use `withClearedState()`:
+
+```php
+$view = $view->withClearedState();
+```
+
+## Extensões
+
+- [yiisoft/yii-view](https://github.com/yiisoft/yii-view) - um wrapper usado na [Estrutura Yii](https://www.yiiframework.com/).
+   Adiciona funcionalidade extra para um ambiente web e compatibilidade
+   com interfaces [PSR-7](https://www.php-fig.org/psr/psr-7).
+- [yiisoft/view-twig](https://github.com/yiisoft/view-twig) - uma extensão que fornece um renderizador de visualização que
+   permite que você use o mecanismo de modelo de visualização [Twig](https://twig.symfony.com), em vez do renderizador PHP padrão.
diff --git a/docs/guides/pt-BR/basic-functionality.md → docs/guide/pt-BR/basic-functionality.md b/docs/guides/pt-BR/basic-functionality.md → docs/guide/pt-BR/basic-functionality.md
diff --git a/docs/guides/pt-BR/use-in-web-environment.md → docs/guide/pt-BR/use-in-web-environment.md b/docs/guides/pt-BR/use-in-web-environment.md → docs/guide/pt-BR/use-in-web-environment.md
diff --git a/docs/internals.md b/docs/internals.md
@@ -0,0 +1,44 @@
+# Internals
+
+## Unit testing
+
+The package is tested with [PHPUnit](https://phpunit.de/). To run tests:
+
+```shell
+./vendor/bin/phpunit
+```
+
+## Mutation testing
+
+The package tests are checked with [Infection](https://infection.github.io/) mutation framework with
+[Infection Static Analysis Plugin](https://github.com/Roave/infection-static-analysis-plugin). To run it:
+
+```shell
+./vendor/bin/roave-infection-static-analysis-plugin
+```
+
+## Static analysis
+
+The code is statically analyzed with [Psalm](https://psalm.dev/). To run static analysis:
+
+```shell
+./vendor/bin/psalm
+```
+
+## Code style
+
+Use [Rector](https://github.com/rectorphp/rector) to make codebase follow some specific rules or
+use either newest or any specific version of PHP:
+
+```shell
+./vendor/bin/rector
+```
+
+## Dependencies
+
+This package uses [composer-require-checker](https://github.com/maglnet/ComposerRequireChecker) to check if
+all dependencies are correctly defined in `composer.json`. To run the checker, execute the following command:
+
+```shell
+./vendor/bin/composer-require-checker
+```