Merge pull request #194 from dotkernel/develop

Update LLMS generation, category names, and fix broken links

Author: arhimede

public/md-articles/php-troubleshooting/fix-installing-pear-packages-with-php-7-2.md

@@ -1,5 +1,5 @@
 ---
-title: "[FIX] Installing PEAR packages with PHP 7.2"
+title: "FIX: Installing PEAR packages with PHP 7.2"
 description: "How to fix the 'Cannot use result of built-in function in write context' PEAR error on PHP 7.2 by patching Archive_Tar's func_get_args() call, and how to reinstall the affected packages afterward."
 author: "Gabi DJ"
 date_published: "2018-05-18"
@@ -8,7 +8,7 @@ category: "PHP Troubleshooting"
 language: "en"
 ---
 
-# [FIX] Installing PEAR packages with PHP 7.2
+# FIX: Installing PEAR packages with PHP 7.2
 
 ## TL;DR
 

public/uploads/article/019f7ea7-116b-72e2-ab4f-e90276d9b8a6/zend.barcode.introduction.example-1.png

@@ -1,6 +1,6 @@
 [
     {
-        "name": "Dotkernel",
+        "name": "Core Components",
         "slug": "dotkernel",
         "isVisible": true,
         "articles": [
@@ -1169,7 +1169,7 @@
             {
                 "post_title": "Zend Framework 1 End-of-Life",
                 "post_date": "2016-06-28 11:22:06",
-                "post_status": "archived",
+                "post_status": "published",
                 "author": {
                     "display_name": "arhimede",
                     "github": "arhimede"
@@ -1238,7 +1238,7 @@
             {
                 "post_title": "Sunsetting PEAR Channel for Zend Framework 1",
                 "post_date": "2022-11-11 12:55:22",
-                "post_status": "archived",
+                "post_status": "published",
                 "author": {
                     "display_name": "arhimede",
                     "github": "arhimede"
@@ -1951,7 +1951,7 @@
                 ]
             },
             {
-                "post_title": "[FIX] Installing PEAR packages with PHP 7.2",
+                "post_title": "FIX: Installing PEAR packages with PHP 7.2",
                 "post_date": "2018-05-18 11:19:49",
                 "post_status": "published",
                 "author": {

src/App/src/Fixture/articles_cleaned.json

@@ -9,6 +9,7 @@
 use RuntimeException;
 
 use function array_key_exists;
+use function array_merge;
 use function basename;
 use function count;
 use function explode;
@@ -28,16 +29,16 @@ class LlmsGenerator
 {
     /** @var list<non-empty-string> */
     private const CATEGORY_ORDER = [
-        'dotkernel',
-        'php-development',
-        'dotkernel-api',
-        'dotkernel3',
         'headless-platform',
-        'middleware',
+        'dotkernel-api',
         'architecture',
-        'design-pattern',
         'how-to',
+        'middleware',
         'best-practice',
+        'design-pattern',
+        'dotkernel3',
+        'dotkernel',
+        'php-development',
     ];
 
     /**
@@ -50,11 +51,40 @@ class LlmsGenerator
         'php-troubleshooting',
         'licensing',
         'phpstorm',
+        'zend-framework',
+    ];
+
+    /**
+     * Individual posts demoted to `## Optional`, keyed by category slug - for a single article
+     * that doesn't warrant moving its whole category into `OPTIONAL_CATEGORIES`.
+     *
+     * @var array<non-empty-string, list<non-empty-string>>
+     */
+    private const array OPTIONAL_POSTS = [
+        'dotkernel'       => [
+            'commitment-to-php-new-zend-certified-engineers-zce-in-our-team',
+            'adding-composer-support-in-your-dotkernel-project',
+            'using-dotkernel-with-composer-dependencies',
+            'forcing-utf8-connections-and-character-set-in-mysql',
+            'adding-a-cors-implementation-to-zend-expressive',
+        ],
+        'best-practice'   => [
+            'insert-update-delete-statements-with-zend-db',
+            'sql-queries-using-zend-db-select',
+            'subqueries-with-zend-db',
+            'using-like-wildcards-with-zend-db',
+            'what-are-returning-the-fetch-functions-from-zend-db',
+        ],
+        'php-development' => [
+            'almalinux-9-in-wsl2-install-php-apache-mariadb-composer-phpmyadmin',
+            'mezzio-app-development-in-wsl2',
+        ],
     ];
 
     /** @var array<non-empty-string, non-empty-string> */
     private const CATEGORY_BLURBS = [
-        'dotkernel'           => 'the core framework - releases, caching, sessions, auth, WURFL/device detection',
+        'dotkernel'           => 'the core framework - dot-* components (caching, logging, mail, dependency injection),'
+            . ' Doctrine integration, and getting started with Dotkernel Light',
         'php-development'     => 'general PHP tooling, environments, IDEs, security',
         'how-to'              => 'practical guides - migrations, CORS, PSR-7, routing',
         'best-practice'       => 'coding standards and database access patterns',
@@ -89,6 +119,15 @@ class LlmsGenerator
      */
     private const string OSS_LIFECYCLE_SLUG = 'dotkernel-packages-oss-lifecycle';
 
+    /**
+     * The Contact page has no `public/contact.md` counterpart to source a title/description
+     * from, so it is hardcoded directly into `## Pages` instead.
+     */
+    private const string CONTACT_TITLE       = 'Contact';
+    private const string CONTACT_PATH        = 'contact/';
+    private const string CONTACT_DESCRIPTION = 'Get in touch, report a security issue, or find where to ask a '
+        . 'question and contribute to the project.';
+
     public function __construct(
         private readonly PostRepository $postRepository,
         private readonly string $sourceDir,
@@ -108,16 +147,20 @@ public function write(): int
     {
         $postsByCategory = $this->groupPublishedPostsByCategory();
 
-        $sections = [];
+        $sections      = [];
+        $optionalLines = [];
         foreach (self::CATEGORY_ORDER as $slug) {
             if (! isset($postsByCategory[$slug])) {
                 continue;
             }
-            $sections[] = $this->buildCategorySection($slug, $postsByCategory[$slug]);
+            [$entries, $demoted] = $this->splitOptionalPosts($slug, $postsByCategory[$slug]);
+            $optionalLines       = array_merge($optionalLines, $demoted);
+            if ($entries !== []) {
+                $sections[] = $this->buildCategorySection($slug, $entries);
+            }
             unset($postsByCategory[$slug]);
         }
 
-        $optionalLines         = [];
         $optionalCategoryCount = 0;
         foreach (self::OPTIONAL_CATEGORIES as $slug) {
             if (! isset($postsByCategory[$slug])) {
@@ -132,7 +175,11 @@ public function write(): int
 
         uasort($postsByCategory, static fn (array $a, array $b): int => count($b) - count($a));
         foreach ($postsByCategory as $slug => $posts) {
-            $sections[] = $this->buildCategorySection($slug, $posts);
+            [$entries, $demoted] = $this->splitOptionalPosts($slug, $posts);
+            $optionalLines       = array_merge($optionalLines, $demoted);
+            if ($entries !== []) {
+                $sections[] = $this->buildCategorySection($slug, $entries);
+            }
         }
 
         $written = $this->buildHeader()
@@ -174,17 +221,40 @@ private function groupPublishedPostsByCategory(): array
         return $byCategory;
     }
 
+    /**
+     * @param list<array{post: Post, title: string, description: string}> $entries
+     * @return array{0: list<array{post: Post, title: string, description: string}>, 1: list<string>}
+     */
+    private function splitOptionalPosts(string $slug, array $entries): array
+    {
+        $optionalSlugs = self::OPTIONAL_POSTS[$slug] ?? [];
+        if ($optionalSlugs === []) {
+            return [$entries, []];
+        }
+
+        $kept     = [];
+        $optional = [];
+        foreach ($entries as $entry) {
+            if (in_array($entry['post']->getSlug(), $optionalSlugs, true)) {
+                $optional[] = $this->buildOptionalPostLink($slug, $entry);
+                continue;
+            }
+
+            $kept[] = $entry;
+        }
+
+        return [$kept, $optional];
+    }
+
     /**
      * @param list<array{post: Post, title: string, description: string}> $entries
      */
     private function buildCategorySection(string $slug, array $entries): string
     {
         $category = $entries[0]['post']->getCategory();
         $heading  = sprintf(
-            '## %s (%d post%s)',
-            $category->getName(),
-            count($entries),
-            count($entries) === 1 ? '' : 's',
+            '## %s',
+            $category->getName()
         );
 
         $lines = [$heading, ''];
@@ -256,7 +326,13 @@ private function buildPagesSection(): string
             return '';
         }
 
-        $pages = [];
+        $pages = [
+            [
+                'title'       => self::CONTACT_TITLE,
+                'path'        => self::CONTACT_PATH,
+                'description' => self::CONTACT_DESCRIPTION,
+            ],
+        ];
         foreach (glob($this->pagesDir . '/*.md') ?: [] as $path) {
             $slug = basename($path, '.md');
             if ($slug === self::OSS_LIFECYCLE_SLUG || in_array($slug, self::DOCS_PAGES, true)) {
@@ -276,24 +352,20 @@ private function buildPagesSection(): string
 
             $pages[] = [
                 'title'       => trim(explode('|', $title, 2)[0]),
-                'slug'        => $slug,
+                'path'        => $slug . '.md',
                 'description' => $description,
             ];
         }
 
-        if ($pages === []) {
-            return '';
-        }
-
         usort($pages, static fn (array $a, array $b): int => strcasecmp($a['title'], $b['title']));
 
         $lines = ['## Pages', ''];
         foreach ($pages as $page) {
             $lines[] = sprintf(
-                '- [%s](%s/%s.md): %s',
+                '- [%s](%s/%s): %s',
                 $page['title'],
                 $this->baseUrl,
-                $page['slug'],
+                $page['path'],
                 $page['description'],
             );
         }
@@ -358,9 +430,6 @@ private function buildHeader(): string
             . 'by category and attributed to an author; URLs follow the pattern `/{category-slug}/{post-slug}/`. '
             . 'Each post also has a Markdown version at `/{category-slug}/{post-slug}.md`.';
 
-        $about = 'the team behind Dotkernel - how the team works, its commitment to open source and the PHP '
-            . 'community, and how it uses AI under guardrails';
-
         return "# {$this->title}\n\n"
             . $intro . "\n\n"
             . $body . "\n\n"

src/App/src/Service/LlmsGenerator.php

@@ -216,8 +216,6 @@
 
 <li><a href="https://docs.dotkernel.org/api-documentation/v6/tutorials/cors/" target="_blank" rel="noreferrer noopener">CORS in Dotkernel API</a></li>
 
-<li><a href="https://www.dotkernel.com/how-to/mezzio-cors-implementation-in-dotkernel/" target="_blank" rel="noreferrer noopener">CORS Policy Setup in Dotkernel</a></li>
-
 <li><a href="https://docs.dotkernel.org/api-documentation/v6/core-features/error-reporting/" target="_blank" rel="noreferrer noopener">Error Reporting Endpoint</a></li>
 
 <li><a href="https://docs.dotkernel.org/api-documentation/v6/openapi/introduction/" target="_blank" rel="noreferrer noopener">OpenAPI Documentation</a></li>

src/Blog/templates/page/blog-resource/best-practice/basic-security-in-dotkernel-headless-platform.html.twig

@@ -1,7 +1,7 @@
 {% extends '@layout/blog-post.html.twig' %}
 
 {% block body %}
-Continuing the Zend_DB article <a href="http://www.dotkernel.com/dotkernel/sql-select-zend-db/" target="_blank" rel="noopener noreferrer">series</a>, we are stopping now at DML statements.</br>
+Continuing the Zend_DB article <a href="http://www.dotkernel.com/dotkernel/sql-queries-using-zend-db-select/" target="_blank" rel="noopener noreferrer">series</a>, we are stopping now at DML statements.</br>
 DML (Data Manipulation Language) statements are statements that change data values in database tables. There are 3 primary DML statements:
 <ul>
     <li>INSERT - Inserting new rows into database tables.

src/Blog/templates/page/blog-resource/best-practice/insert-update-delete-statements-with-zend-db.html.twig

@@ -87,9 +87,9 @@ echo $select->__toString();exit;
 </pre>
 </br>
 Also see:
- - <a href="http://www.dotkernel.com/best-practice/sql-fetch-zend-db/">What are returning the FETCH functions from Zend_Db</a></br>
- - <a href="http://www.dotkernel.com/best-practice/subqueris-with-zend-db/">Subqueries with Zend_Db</a></br>
- - <a href="http://www.dotkernel.com/best-practice/iud-statements-with-zend-d/">INSERT, UPDATE, DELETE statements with Zend_Db</a>
+ - <a href="http://www.dotkernel.com/best-practice/what-are-returning-the-fetch-functions-from-zend-db/">What are returning the FETCH functions from Zend_Db</a></br>
+ - <a href="http://www.dotkernel.com/best-practice/subqueries-with-zend-db/">Subqueries with Zend_Db</a></br>
+ - <a href="http://www.dotkernel.com/best-practice/insert-update-delete-statements-with-zend-db/">INSERT, UPDATE, DELETE statements with Zend_Db</a>
 
 <h2 id="user-content-faq">Frequently Asked Questions</h2>
 

src/Blog/templates/page/blog-resource/best-practice/sql-queries-using-zend-db-select.html.twig

@@ -1,7 +1,7 @@
 {% extends '@layout/blog-post.html.twig' %}
 
 {% block body %}
-Continuing the Zend_DB article <a href="http://www.dotkernel.com/dotkernel/sql-select-zend-db/" target="_blank" rel="noopener noreferrer">series</a>, we are stopping now at subqueries.
+Continuing the Zend_DB article <a href="http://www.dotkernel.com/dotkernel/sql-queries-using-zend-db-select/" target="_blank" rel="noopener noreferrer">series</a>, we are stopping now at subqueries.
 </br>
 As you note, the below is a complicate query, with <i>COUNT()</i>, <i>LEFT JOIN()</i>, <i>GROUP BY</i>
  - select from 3 tables, and make a count from 2 different tables:

src/Blog/templates/page/blog-resource/best-practice/subqueries-with-zend-db.html.twig

@@ -1,7 +1,7 @@
 {% extends '@layout/blog-post.html.twig' %}
 
 {% block body %}
-Continuing the Zend_Db article <a href="http://www.dotkernel.com/dotkernel/sql-select-zend-db/" target="_blank" rel="noopener noreferrer">series</a>, let's discuss the LIKE condition.
+Continuing the Zend_Db article <a href="http://www.dotkernel.com/dotkernel/sql-queries-using-zend-db-select/" target="_blank" rel="noopener noreferrer">series</a>, let's discuss the LIKE condition.
 
 The <strong>LIKE </strong>condition allows you to use wildcards in the <em>WHERE </em>clause of an SQL statement. This allows pattern matching. It can be used in any valid SQL statement (<em>SELECT</em>, <em>INSERT</em>, <em>UPDATE </em>or <em>DELETE</em>).
 

src/Blog/templates/page/blog-resource/best-practice/using-like-wildcards-with-zend-db.html.twig

@@ -1,7 +1,7 @@
 {% extends '@layout/blog-post.html.twig' %}
 
 {% block body %}
-Continuing the Zend_DB article <a href="http://www.dotkernel.com/dotkernel/sql-select-zend-db/" target="_blank" rel="noopener noreferrer">series</a>, we are stopping now at <i>FETCH</i> methods that are in <a href="https://docs.laminas.dev/laminas-db/adapter/" target="_blank" rel="noopener noreferrer">Zend_Db_Adapter_Abstract</a>:
+Continuing the Zend_DB article <a href="http://www.dotkernel.com/dotkernel/sql-queries-using-zend-db-select/" target="_blank" rel="noopener noreferrer">series</a>, we are stopping now at <i>FETCH</i> methods that are in <a href="https://docs.laminas.dev/laminas-db/adapter/" target="_blank" rel="noopener noreferrer">Zend_Db_Adapter_Abstract</a>:
 <pre>
 array  fetchAll  (string|Zend_Db_Select $sql, , )
 array fetchAssoc (string|Zend_Db_Select $sql, [mixed $bind = array()])