README

Pamytools is a high-performance, fault-tolerant PHP 8.2+ framework designed for async HTTP transport, web scraping resilience via Circuit Breakers, and auto-hydration of HTML/Regex into typed DTOs using native PHP Attributes.

✨ Features

⚡ Async HTTP Engine: High-concurrency native multi-cURL transport driver.
🛡️ Circuit Breaker Pattern: Prevent cascading failures with customizable thresholds.
🏷️ Native PHP Attributes: Declarative mapping of DOMXPath and Regex into strongly-typed DTOs.
🌐 Built-in I18n: Multi-language exception and message translator out of the box (pt-BR, en-US, es-ES).
🛠️ SOLID Architecture: Clean, extensible interfaces designed for testability and high coverage.

📋 Requirements

PHP: ^8.2
Extensions: ext-curl, ext-dom, ext-json, ext-libxml

📦 Installation

Install the package via Composer:

composer require pamellayamada/pamytools

🚀 Quick Start

1. Define your DTO with Native Attributes

Use #[ExtractPath] to declaratively map HTML elements or Regex patterns directly into your Data Transfer Object properties.

namespace App\DTOs;

use Pamytools\Attributes\ExtractPath;

final readonly class CompanyDTO 
{
    public function __construct(
        #[ExtractPath(query: "//h1[@class='title']")]
        public ?string $companyName,

        #[ExtractPath(query: '/token=([a-z0-9]+)/', type: 'regex')]
        public ?string $csrfToken
    ) {}
}

2. Fetch & Auto-Hydrate with Resilience

Combine the async transport engine, the Circuit Breaker pattern, and the Data Hydrator into a seamless execution pipeline:

use App\DTOs\CompanyDTO;
use Pamytools\Http\AsyncHttpEngine;
use Pamytools\Resilience\CircuitBreaker;
use Pamytools\Parser\DataHydrator;
use Pamytools\I18n\Translator;

// 1. Set global translation locale (Default: pt-BR. Available: en-US, es-ES, pt-BR)
Translator::setLocale('en-US');

// 2. Initialize HTTP client and Circuit Breaker guard
$http = new AsyncHttpEngine();
$breaker = new CircuitBreaker(serviceName: 'ExternalAPI', failureThreshold: 3);

// 3. Execute request safely
$response = $breaker->execute(
    fn() => $http->send('GET', 'https://example.com')
);

// 4. Hydrate HTML directly into DTO
$hydrator = new DataHydrator();

/** @var CompanyDTO $dto */
$dto = $hydrator->hydrate($response->body, CompanyDTO::class);

echo $dto->companyName; // Outputs extracted text from //h1[@class='title']

🏗️ Project Architecture

pamytools/
├── .github/
│   └── workflows/
│       └── tests.yml                 <-- CI/CD Pipeline
├── lang/                             <-- I18n Translation Dictionaries
│   ├── en-US.json
│   ├── es-ES.json
│   └── pt-BR.json
├── src/
│   ├── Attributes/
│   │   └── ExtractPath.php           <-- PHP 8.2+ Attribute definition
│   ├── Contracts/
│   │   ├── HttpClientInterface.php   <-- SOLID Interfaces
│   │   └── HydratorInterface.php
│   ├── Exception/
│   │   ├── PamytoolsException.php    <-- Translated Core Exceptions
│   │   ├── CircuitBreakerOpenException.php
│   │   └── HydrationException.php
│   ├── Http/
│   │   ├── AsyncHttpEngine.php       <-- Native Multi-cURL Driver
│   │   └── HttpResponse.php
│   ├── I18n/
│   │   └── Translator.php            <-- Global Translation Engine
│   ├── Parser/
│   │   └── DataHydrator.php          <-- Hydration Engine (DOMXPath/Regex)
│   └── Resilience/
│       └── CircuitBreaker.php        <-- Circuit Breaker Guard
└── tests/                            <-- PHPUnit Test Suite

🧪 Testing

Run tests with PHPUnit:

composer test

📄 License

This project is licensed under the MIT License.

pamellayamada / pamytools

Maintainers

Package info

Statistics

Security