Skip to content
Maatify-ltdPublic

About

Scoped slug lifecycle and canonicalization for PHP applications.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

20 Commits

Folders and files

Repository files navigation

Maatify Slug

Maatify.dev

Status Artifact target Published at qualification PHP License PHPStan

Packagist Monthly Downloads Total Downloads Maatify Ecosystem Install published RC.2 Install after publication

Usage Guide Examples Package Reference Changelog Security Policy Contributing Guide

An independent PHP slug lifecycle engine with clear boundaries between the slug domain, the Host, URLs, HTTP, and SEO.


Publication State

Release target: 1.0.0-rc.3, a Pre-Stable Release Candidate.

At qualification, 1.0.0-rc.3 is unpublished and 1.0.0-rc.2 is available through Packagist. No Stable support line is established.

The current public contract is owned by SLUG_PACKAGE_REFERENCE.md. Execution evidence is maintained in GitHub PR and CI history rather than duplicated in this consumer-facing README.

The requirements and examples below are for RC.3.

Package Summary

maatify/php-slug is a standalone PHP library for slug generation, canonicalization, scoped ownership, lifecycle management, aliases, history, resolution, and package-owned PDO MySQL persistence.

Key Features

  • Slug Generation & Canonicalization: Consistent generation and canonicalization through versioned built-in profiles.
  • Ownership & Lifecycle: Exact claiming, generated allocation, release, scope transition, atomic transfer, and adoption.
  • Aliases & History: Active and retired aliases with immutable lifecycle history.
  • Persistence & Concurrency: PDO MySQL-compatible persistence with transactions, CAS, and concurrency guarantees.
  • Resolution & Management: Resolution, availability, Scope discovery, Scope operational summaries, operational History windows, and management reads with shared pagination.
  • Public Extension: Versioned custom Slug profiles through the public registry path, plus Host-owned reserved-slug policy injection.

Requirements

Requirement Value
PHP (Composer) >=8.4.27 <8.5.0 || >=8.5.12 <9.0.0
Database PDO MySQL; mysql:8.0.36 is the CI reproducibility target
Extensions ext-filter, ext-intl, ext-mbstring, ext-pdo, ext-pdo_mysql
Direct packages maatify/exceptions ^1.0, maatify/shared-common ^1.0, maatify/php-persistence 1.0.0-rc.2 (temporary RC dependency)

CI verifies PHP 8.4 and 8.5. Composer also admits newer PHP 8 minors within this range. Each newer minor needs its own security and compatibility evidence before it can be listed as supported.

Built-in profiles require the normalization and transliteration capabilities provided by ext-intl; the package verifies those capabilities at runtime. No exact ICU or Unicode version is required from the consumer.

Installation

Once RC.3 is published to Packagist, install the exact target and its Persistence dependency using the following command. Keep your project's minimum-stability set to stable; the two @RC allowances apply to these packages.

composer require maatify/php-slug:1.0.0-rc.3@RC maatify/php-persistence:1.0.0-rc.2@RC

Upgrading from RC.2. Stop Slug traffic and apply the additive 003_registry_lock_projection.sql migration before enabling the RC.3 persisted runtime. Follow the schema upgrade guide for the backfill and verification steps. Update any pagination imports from the retired maatify/persistence dependency to the types from maatify/php-persistence.

Published RC.2

1.0.0-rc.2 was the published version at RC.3 qualification. To install that exact earlier version:

composer require maatify/php-slug:1.0.0-rc.2@RC

Use the versioned RC.2 usage guide.

Quick Usage

The stateless path does not require a database or Host framework:

$profiles = SlugProfileRegistryFactory::createBuiltIn();
$text = SlugTextServiceFactory::create($profiles);
$slug = $text->generateFromSource(
    new SlugProfileKey('ascii-v1'),
    'Hello, World!',
);
// $slug->slug->value === 'hello-world'

For the persisted path, the Host injects a PDO connection, a ReservedSlugPolicyInterface, and a ClockInterface into SlugEngineFactory::create(...). See docs/guides/USAGE_GUIDE.md for the complete workflow.

Public Runtime API

The public Runtime provides actual paths for:

  • canonicalization through SlugTextServiceInterface, generateFromSource, canonicalizeClaim, and canonicalizeLookup;
  • lifecycle ownership through SlugEngine and SlugLifecycleServiceInterface, including assignExact;
  • consumer reads through checkAvailability, getCurrent, and resolve; and
  • management reads through SlugManagementQueryInterface, including searchScopes, getScopeOperationalSummary, and searchHistory.

This overview does not replace the complete inventory and contracts in SLUG_PACKAGE_REFERENCE.md.

Examples

The canonicalization and custom-profile examples run without Docker. Run the persisted example from a repository checkout using the examples smoke verification.

Documentation

Transactions and Concurrency

On the persisted path, the package owns the transaction when the Host has no outer transaction and uses a savepoint when participating in an outer transaction where the capability is supported. Exact claims rely on the unique Registry constraint as the final race authority and use lifecycle mutation CAS and idempotency according to the contract. See SLUG_PACKAGE_REFERENCE.md for the normative details.

Security and Trust Boundaries

The Host owns the connection, PDO configuration, entity existence, routing, HTTP, SEO, and authorization. The package does not create hidden connections or use Host foreign keys or joins. For vulnerability reports, see Security Policy; do not disclose private vulnerability details through GitHub Issues.

Exceptions and Error Propagation

Package-defined semantic and domain failures use the SlugExceptionInterface / SlugDomainExceptionInterface hierarchy described in the Package Reference. External infrastructure Throwable instances, including PDO failures outside the documented semantic conversions, may propagate unchanged according to the current contract.

Quality Status

The package is maintained behind the repository's configured CI and quality gates. Current execution evidence is maintained in GitHub PR and CI history.

Development and Testing

For repository setup, tests, and example gates, see CONTRIBUTING.md. The persisted example uses the checkout’s disposable MySQL service.

License

Licensed under the MIT License.

👤 Author

Engineered by Mohamed Abdulalim (@megyptm)
Backend Lead & Technical Architect
https://www.maatify.dev


About

Scoped slug lifecycle and canonicalization for PHP applications.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Contributors

Languages