README

Laravel package for receiving articles from external systems.

PL

Opis

Paczka udostepnia gotowe API do odbioru artykulow oraz powiazanych zasobow (autorzy, kategorie, tagi, media). Zawiera walidacje, idempotency, limity rate oraz punkty zaczepienia (hooks) do integracji z Twoja logika.

Wymagania

• PHP 8.5+
• Laravel 11 lub 12
• Laravel Sanctum

Instalacja

composer require taqie/laravel-article-receiver

Konfiguracja

Publikacja configu:

php artisan vendor:publish --tag=article-receiver-config

Publikacja migracji (opcjonalnie):

php artisan vendor:publish --tag=article-receiver-migrations

Hooki

Przyklady hookow przed/po create/update/delete:

// config/article-receiver.php
'hooks' => [
    'before_create' => fn (ArticleData $data) => $data,
    'after_create' => fn (Article $article, ArticleData $data) => null,
    'before_update' => fn (Article $article, ArticleData $data) => $data,
    'after_update' => fn (Article $article, ArticleData $data) => null,
    'before_delete' => fn (Article $article) => null,
    'after_delete' => fn (int $articleId, array $payload) => null,
    'author' => [
        'before_create' => fn (AuthorData $data) => $data,
        'after_create' => fn (Author $author, AuthorData $data) => null,
    ],
    'category' => [
        'before_create' => fn (CategoryData $data) => $data,
        'after_create' => fn (Category $category, CategoryData $data) => null,
    ],
    'tag' => [
        'before_create' => fn (TagData $data) => $data,
        'after_create' => fn (Tag $tag, TagData $data) => null,
    ],
    'media' => [
        'before_create' => fn (UploadedFile $file, ?string $altText, ?int $articleId, ?string $folder) => null,
        'after_create' => fn (Media $media) => null,
    ],
],

Hooki moga byc closure, Class@method lub callable array. before_* moze zwrocic zmodyfikowany DTO.

Nadpisywanie zasobow (Resources)

// config/article-receiver.php
'response' => [
    'resource' => null,
    'resources' => [
        'article' => \App\Http\Resources\ArticleResource::class,
        'author' => \App\Http\Resources\AuthorResource::class,
        'category' => \App\Http\Resources\CategoryResource::class,
        'tag' => \App\Http\Resources\TagResource::class,
        'media' => \App\Http\Resources\MediaResource::class,
    ],
],

Mapowanie pol

// config/article-receiver.php
'field_mapping' => [
    'title' => 'headline',
    'lead' => 'excerpt',
    'meta_description' => 'meta_desc',
    'body' => 'content',
    'author_id' => 'user_id',
    'category_id' => 'section_id',
    'featured_image_url' => 'featured_image',
    'published_at' => 'published_at',
    'metadata' => 'metadata',
],

Mapowanie jest stosowane przy create/update artykulu.

Prefix tabel

// config/article-receiver.php
'table_prefix' => 'ar_',

Domyslnie tabele maja prefix ar_, np. ar_articles.

Testy i pokrycie

Uruchomienie testow:

vendor/bin/pest

Pokrycie kodu (wymaga wsparcia Xdebug lub PCOV):

vendor/bin/pest --coverage

EN

Overview

Provides a ready-to-use API for receiving articles and related resources (authors, categories, tags, media). Includes validation, idempotency, rate limits, and hooks for integration with your own logic.

Requirements

• PHP 8.5+
• Laravel 11 or 12
• Laravel Sanctum

Installation

composer require taqie/laravel-article-receiver

Configuration

Publish config:

php artisan vendor:publish --tag=article-receiver-config

Publish migrations (optional):

php artisan vendor:publish --tag=article-receiver-migrations

Hooks

// config/article-receiver.php
'hooks' => [
    'before_create' => fn (ArticleData $data) => $data,
    'after_create' => fn (Article $article, ArticleData $data) => null,
    'before_update' => fn (Article $article, ArticleData $data) => $data,
    'after_update' => fn (Article $article, ArticleData $data) => null,
    'before_delete' => fn (Article $article) => null,
    'after_delete' => fn (int $articleId, array $payload) => null,
    'author' => [
        'before_create' => fn (AuthorData $data) => $data,
        'after_create' => fn (Author $author, AuthorData $data) => null,
    ],
    'category' => [
        'before_create' => fn (CategoryData $data) => $data,
        'after_create' => fn (Category $category, CategoryData $data) => null,
    ],
    'tag' => [
        'before_create' => fn (TagData $data) => $data,
        'after_create' => fn (Tag $tag, TagData $data) => null,
    ],
    'media' => [
        'before_create' => fn (UploadedFile $file, ?string $altText, ?int $articleId, ?string $folder) => null,
        'after_create' => fn (Media $media) => null,
    ],
],

Hooks can be closures, Class@method strings, or callable arrays. before_* hooks may return a modified DTO.

Resource Overrides

// config/article-receiver.php
'response' => [
    'resource' => null,
    'resources' => [
        'article' => \App\Http\Resources\ArticleResource::class,
        'author' => \App\Http\Resources\AuthorResource::class,
        'category' => \App\Http\Resources\CategoryResource::class,
        'tag' => \App\Http\Resources\TagResource::class,
        'media' => \App\Http\Resources\MediaResource::class,
    ],
],

Field Mapping

// config/article-receiver.php
'field_mapping' => [
    'title' => 'headline',
    'lead' => 'excerpt',
    'meta_description' => 'meta_desc',
    'body' => 'content',
    'author_id' => 'user_id',
    'category_id' => 'section_id',
    'featured_image_url' => 'featured_image',
    'published_at' => 'published_at',
    'metadata' => 'metadata',
],

Mapping is applied in the article create/update actions before saving.

Table prefix

// config/article-receiver.php
'table_prefix' => 'ar_',

By default tables use the ar_ prefix, e.g. ar_articles.

Testing and coverage

vendor/bin/pest

Coverage (requires Xdebug or PCOV):

vendor/bin/pest --coverage

Status

This package is under active development. See docs/PLAN-LARAVEL-PACKAGE-ARTICLE-RECEIVER.md for the roadmap.

Documentation

• Integration guide: docs/INTEGRATION-GUIDE.md
• API specification: docs/TARGET-SITE-API-SPECIFICATION.md
• OpenAPI (Markdown): docs/OPENAPI.md

License

MIT.