Add Composer-installable WordPress query argument builders

.github/workflows/tests.yml

@@ -0,0 +1,46 @@
+name: Tests
+
+on:
+  push:
+    branches:
+      - "**"
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  tests:
+    name: PHP ${{ matrix.php }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        php:
+          - "8.0"
+          - "8.1"
+          - "8.2"
+          - "8.3"
+          - "8.4"
+          - "8.5"
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php }}
+          coverage: none
+          tools: composer:v2
+
+      - name: Validate Composer configuration
+        run: composer validate --strict
+
+      - name: Install dependencies
+        run: composer update --prefer-dist --no-interaction
+
+      - name: Run unit tests
+        run: composer test

.gitignore

@@ -0,0 +1,4 @@
+/vendor/
+/.phpunit.cache/
+/.phpunit.result.cache
+/composer.lock

README.md

@@ -1 +1,89 @@
-# wordpress-database
+# Pentarix WordPress Database
+
+Composer-installable WordPress query argument builders with a fluent API.
+
+This package currently provides the WordPress query argument-building capabilities extracted from Vertex Framework. It builds argument arrays; it does not execute queries or provide an ORM.
+
+## Requirements
+
+- PHP 8.0 or later
+- WordPress 6.3 or later when passing generated arguments to WordPress APIs
+
+## Installation
+
+```bash
+composer require pentarix/wordpress-database
+```
+
+Composer maps the `Pentarix\WordPressDatabase\` namespace to `src/` using PSR-4.
+
+## Usage
+
+```php
+use Pentarix\WordPressDatabase\WordPress\MetaQueryArg;
+use Pentarix\WordPressDatabase\WordPress\PostQueryArg;
+
+$args = PostQueryArg::make()
+    ->postType('product')
+    ->postStatus('publish')
+    ->postsPerPage(12)
+    ->metaQuery(MetaQueryArg::make()->where('featured', true))
+    ->toArray();
+
+$query = new \\WP_Query($args);
+```
+
+## Available builders
+
+- `CommentQueryArg`
+- `DateQueryArg`
+- `MetaQueryArg`
+- `NetworkQueryArg`
+- `PostQueryArg`
+- `SiteQueryArg`
+- `TaxQueryArg`
+- `TermQueryArg`
+- `UserQueryArg`
+
+Supporting builders (`IncludeQueryArg`, `IncludeExcludeQueryArg`, `IncludeExcludeIsQueryArg`, and `SearchQueryArg`) are also available under `Pentarix\WordPressDatabase\WordPress`.
+
+## Argument coverage
+
+The main query builders retain the arguments supplied to their constructors and expose
+`set()` and `setMany()` for WordPress query variables that do not have a dedicated
+convenience method yet. These methods preserve the supplied key and value without
+rewriting WordPress's query contract:
+
+```php
+$args = PostQueryArg::make()
+    ->set('author', 12)
+    ->set('post_mime_type', ['image/jpeg', 'image/png'])
+    ->setMany([
+        'search_columns' => ['post_title', 'post_excerpt'],
+        'update_menu_item_cache' => false,
+    ])
+    ->toArray();
+```
+
+The builder-specific fluent methods remain the preferred interface for commonly used
+arguments and nested query clauses. The generic setters provide pass-through coverage
+for additional core arguments and custom query variables supported by WordPress hooks.
+Values are passed to WordPress as supplied; WordPress remains responsible for query
+interpretation and execution.
+
+## Scope
+
+The builders return arrays compatible with WordPress query APIs, including `WP_Query`, `WP_User_Query`, `WP_Comment_Query`, `WP_Term_Query`, and multisite query APIs.
+
+They do not execute database queries, replace WordPress query classes, or bypass WordPress's query lifecycle. Direct SQL, custom-table CRUD, repositories, models, and migrations are outside the current scope.
+
+## Development
+
+```bash
+composer install
+composer test
+```
+
+## Licence
+
+MIT. See [LICENSE](LICENSE).

composer.json

@@ -0,0 +1,27 @@
+{
+    "name": "pentarix/wordpress-database",
+    "description": "WordPress query argument builders with a fluent, Composer-autoloadable API.",
+    "type": "library",
+    "license": "MIT",
+    "require": {
+        "php": ">=8.0"
+    },
+    "require-dev": {
+        "phpunit/phpunit": "^9.6 || ^10.5 || ^11.5 || ^12.0"
+    },
+    "autoload": {
+        "psr-4": {
+            "Pentarix\\WordPressDatabase\\": "src/"
+        }
+    },
+    "autoload-dev": {
+        "psr-4": {
+            "Pentarix\\WordPressDatabase\\Tests\\": "tests/"
+        }
+    },
+    "scripts": {
+        "test": "phpunit --configuration phpunit.xml"
+    },
+    "minimum-stability": "stable",
+    "prefer-stable": true
+}

phpunit.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit bootstrap="tests/bootstrap.php" colors="true" failOnRisky="true" failOnWarning="true">
+    <testsuites>
+        <testsuite name="WordPress Database Unit Tests">
+            <directory>tests/WordPress</directory>
+        </testsuite>
+    </testsuites>
+</phpunit>

src/Utils/ArrayUtil.php

@@ -0,0 +1,95 @@
+<?php
+
+/**
+ * @author    Sina Kuhestani <sinakuhestani@gmail.com>
+ * @copyright 2026 Sina Kuhestani (EphpicMan)
+ * @link      https://github.com/ephpicman GitHub
+ * @link      https://www.linkedin.com/in/ephpicman LinkedIn
+ * @license   See the LICENSE file in the project root.
+ */
+
+declare(strict_types=1);
+
+namespace Pentarix\WordPressDatabase\Utils;
+
+final class ArrayUtil
+{
+    public static function castValues(
+        int|float|string|array $value,
+        callable $cast
+    ): array {
+        $values = \is_array($value) ? $value : [$value];
+
+        return \array_values(
+            \array_unique(
+                \array_map($cast, $values),
+                SORT_REGULAR
+            )
+        );
+    }
+    public static function mergeCasted(
+        array $current,
+        int|float|string|array $value,
+        callable $cast
+    ): array {
+        return \array_values(
+            \array_unique(
+                \array_merge(
+                    $current,
+                    self::castValues($value, $cast)
+                ),
+                SORT_REGULAR
+            )
+        );
+    }
+
+    public static function normalizeUniqueStrings(array $values): array
+    {
+        return \array_values(
+            \array_unique(
+                \array_filter(
+                    $values,
+                    static function ($value): bool {
+                        if (!\is_string($value)) {
+                            throw new \InvalidArgumentException(
+                                'Every value must be a string.'
+                            );
+                        }
+
+                        return '' !== $value;
+                    }
+                ),
+                SORT_STRING
+            )
+        );
+    }
+
+    public static function mergeUnique(array ...$arrays): array
+    {
+        return \array_values(
+            \array_unique(
+                \array_merge(...$arrays),
+                SORT_REGULAR
+            )
+        );
+    }
+
+    public static function removeValues(
+        array $current,
+        array $values,
+        bool $strict = false
+    ): array {
+        if (!$strict) {
+            return \array_values(
+                \array_diff($current, $values)
+            );
+        }
+
+        return \array_values(
+            \array_filter(
+                $current,
+                static fn($item): bool => !\in_array($item, $values, true)
+            )
+        );
+    }
+}

src/Utils/NumberUtil.php

@@ -0,0 +1,20 @@
+<?php
+
+/**
+ * @author    Sina Kuhestani <sinakuhestani@gmail.com>
+ * @copyright 2026 Sina Kuhestani (EphpicMan)
+ * @link      https://github.com/ephpicman GitHub
+ * @link      https://www.linkedin.com/in/ephpicman LinkedIn
+ * @license   See the LICENSE file in the project root.
+ */
+
+declare(strict_types=1);
+namespace Pentarix\WordPressDatabase\Utils;
+
+final class NumberUtil
+{
+    public static function absint(int|float|string $value): int
+    {
+        return (int) abs((float) $value);
+    }
+}