Add friendly exceptions + support Link and Meta tag objects + adopt t…

…o new yiisoft/view (#30)

composer.json

@@ -21,9 +21,10 @@
         "php": "^7.4|^8.0",
         "psr/container-implementation": "1.0.0",
         "yiisoft/aliases": "^1.1|^2.0",
-        "yiisoft/arrays": "^1.0",
         "yiisoft/csrf": "^1.0",
         "yiisoft/data-response": "^3.0@dev",
+        "yiisoft/friendly-exception": "^1.0",
+        "yiisoft/html": "^1.2",
         "yiisoft/strings": "^2.0",
         "yiisoft/view": "^3.0@dev"
     },

psalm.xml

@@ -1,14 +1,11 @@
 <?xml version="1.0"?>
 <psalm
-    errorLevel="2"
+    errorLevel="1"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xmlns="https://getpsalm.org/schema/config"
     xsi:schemaLocation="https://getpsalm.org/schema/config vendor/vimeo/psalm/config.xsd"
 >
     <projectFiles>
         <directory name="src" />
-        <ignoreFiles>
-            <directory name="vendor" />
-        </ignoreFiles>
     </projectFiles>
 </psalm>

src/CsrfViewInjection.php

@@ -14,6 +14,7 @@ final class CsrfViewInjection implements
 {
     public const DEFAULT_META_ATTRIBUTE_NAME = 'csrf';
     public const DEFAULT_PARAMETER_NAME = 'csrf';
+    public const META_TAG_KEY = 'csrf';
 
     private string $metaAttributeName = self::DEFAULT_META_ATTRIBUTE_NAME;
     private string $parameterName = self::DEFAULT_PARAMETER_NAME;
@@ -61,8 +62,7 @@ public function getLayoutParameters(): array
     public function getMetaTags(): array
     {
         return [
-            [
-                '__key' => 'csrf_meta_tags',
+            self::META_TAG_KEY => [
                 'name' => $this->metaAttributeName,
                 'content' => $this->csrfToken->getValue(),
             ],

src/Exception/InvalidLinkTagException.php

@@ -0,0 +1,74 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\Yii\View\Exception;
+
+use RuntimeException;
+use Yiisoft\FriendlyException\FriendlyExceptionInterface;
+
+final class InvalidLinkTagException extends RuntimeException implements FriendlyExceptionInterface
+{
+    /**
+     * @var mixed
+     */
+    private $tag;
+
+    /**
+     * @param mixed $tag
+     */
+    public function __construct(string $message, $tag)
+    {
+        $this->tag = $tag;
+
+        parent::__construct($message);
+    }
+
+    public function getName(): string
+    {
+        return 'Invalid link tag configuration in injection';
+    }
+
+    public function getSolution(): ?string
+    {
+        $solution = 'Got link tag:' . "\n" . var_export($this->tag, true);
+        $solution .= <<<SOLUTION
+
+
+In injection that implements `Yiisoft\Yii\View\LinkTagsInjectionInterface` defined link tags in the method `getLinkTags()`.
+
+The link tag can be define in the following ways:
+
+- as array of attributes: `['rel' => 'stylesheet', 'href' => '/user.css']`,
+- as instance of `Yiisoft\Html\Tag\Link`: `Html::link()->toCssFile('/main.css')`.
+
+Optionally:
+ - use array format and set the position in a page via `__position`.
+ - use string keys of array as identifies the link tag.
+
+Example:
+
+```php
+public function getLinkTags(): array
+{
+	return [
+		'favicon' => Html::link('/myicon.png', [
+			'rel' => 'icon',
+			'type' => 'image/png',
+		]),
+		'themeCss' => [
+			'__position' => \Yiisoft\View\WebView::POSITION_END,
+			Html::link()->toCssFile('/theme.css'),
+		],
+		'userCss' => [
+			'__position' => \Yiisoft\View\WebView::POSITION_BEGIN,
+			'rel' => 'stylesheet',
+			'href' => '/user.css',
+		],
+	];
+}
+```
+SOLUTION;
+        return $solution;
+    }
+}

src/Exception/InvalidMetaTagException.php

@@ -0,0 +1,64 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\Yii\View\Exception;
+
+use RuntimeException;
+use Yiisoft\FriendlyException\FriendlyExceptionInterface;
+
+final class InvalidMetaTagException extends RuntimeException implements FriendlyExceptionInterface
+{
+    /**
+     * @var mixed
+     */
+    private $tag;
+
+    /**
+     * @param mixed $tag
+     */
+    public function __construct(string $message, $tag)
+    {
+        $this->tag = $tag;
+
+        parent::__construct($message);
+    }
+
+    public function getName(): string
+    {
+        return 'Invalid meta tag configuration in injection';
+    }
+
+    public function getSolution(): ?string
+    {
+        $solution = 'Got meta tag:' . "\n" . var_export($this->tag, true);
+        $solution .= <<<SOLUTION
+
+
+In injection that implements `Yiisoft\Yii\View\MetaTagsInjectionInterface` defined meta tags in the method `getMetaTags()`.
+
+The meta tag can be define in the following ways:
+
+- as array of attributes: `['name' => 'keywords', 'content' => 'yii,framework']`,
+- as instance of `Yiisoft\Html\Tag\Meta`: `Html::meta()->name('keywords')->content('yii,framework')`.
+
+Optionally, you may use string keys of array as identifies the meta tag.
+
+Example:
+
+```php
+public function getMetaTags(): array
+{
+    return [
+        'seo-keywords' => [
+            'name' => 'keywords',
+            'content' => 'yii,framework',
+        ],
+        Html::meta()->name('description')->content('Yii is a fast, secure, and efficient PHP framework.'),
+    ];
+}
+```
+SOLUTION;
+        return $solution;
+    }
+}

src/LinkTagsInjectionInterface.php

@@ -4,27 +4,48 @@
 
 namespace Yiisoft\Yii\View;
 
+/**
+ * @psalm-type LinkTagAsArray = array{
+ *   __position?:int,
+ * }&array<string,mixed>
+ * @psalm-type LinkTagsConfig = array<array-key, \Yiisoft\Html\Tag\Link|LinkTagAsArray|array{
+ *   __position?:int,
+ *   0:\Yiisoft\Html\Tag\Link
+ * }>
+ */
 interface LinkTagsInjectionInterface
 {
     /**
      * Returns array of link tags for register via {@see \Yiisoft\View\WebView::registerLinkTag()}.
-     * Optionally, you may set the key that identifies the link tag via `__key`.
+     * Optionally:
+     *  - use array format and set the position in a page via `__position`.
+     *  - use string keys of array as identifies the link tag.
      *
      * For example:
      *
      * ```php
      * [
-     *     [
-     *         '__key' => 'favicon',
+     *     Html::link()->toCssFile('/main.css'),
+     *     'favicon' => Html::link('/myicon.png', [
      *         'rel' => 'icon',
      *         'type' => 'image/png',
-     *         'href' => '/myicon.png',
+     *     ]),
+     *     'themeCss' => [
+     *         '__position' => \Yiisoft\View\WebView::POSITION_END,
+     *         Html::link()->toCssFile('/theme.css'),
+     *     ],
+     *     'userCss' => [
+     *         '__position' => \Yiisoft\View\WebView::POSITION_BEGIN,
+     *         'rel' => 'stylesheet',
+     *         'href' => '/user.css',
      *     ],
      *     ...
      * ]
      * ```
      *
-     * @return array[]
+     * @return array
+     *
+     * @psalm-return LinkTagsConfig
      */
     public function getLinkTags(): array;
 }

src/MetaTagsInjectionInterface.php

@@ -4,26 +4,36 @@
 
 namespace Yiisoft\Yii\View;
 
+/**
+ * @psalm-type MetaTagsConfig = array<array-key, \Yiisoft\Html\Tag\Meta|array<string,mixed>>
+ */
 interface MetaTagsInjectionInterface
 {
     /**
      * Returns array of meta tags for register via {@see \Yiisoft\View\WebView::registerMetaTag()}.
-     * Optionally, you may set the key that identifies the meta tag via `__key`.
+     * Optionally, you may use string keys of array as identifies the meta tag.
      *
      * For example:
      *
      * ```php
      * [
+     *     Html::meta()->name('keywords')->content('yii,framework'),
+     *     'noindex' => Html::meta()->name('robots')->content('noindex'),
      *     [
-     *         '__key' => 'description',
-     *          'name' => 'description',
-     *          'content' => 'This website is about funny raccoons.'
+     *         'name' => 'description',
+     *         'content' => 'This website is about funny raccoons.',
+     *     ],
+     *     'keywords' => [
+     *         'name' => 'keywords',
+     *         'content' => 'yii,framework',
      *     ],
      *     ...
      * ]
      * ```
      *
-     * @return array[]
+     * @return array
+     *
+     * @psalm-return MetaTagsConfig
      */
     public function getMetaTags(): array;
 }