Pierwsza minuta po composer require decyduje, czy pakiet wydaje się godny zaufania. README powinno pokazać instalację, konfigurację i pierwszy udany rezultat, zanim wyjaśni szczegóły wewnętrzne.
composer require dominik-dev/laravel-webhook-tap
php artisan vendor:publish --tag=webhook-tap-config
php artisan migrate
Następnie pokaż maleńki przykład, który zapisuje lub odczytuje jeden webhook. Ogranicz badge'e do informacji, na które użytkownik może zareagować: stanu CI, stabilnej wersji, licencji oraz zgodności PHP/Laravel. Dziesięć badge'y to szum wizualny, nie dowód.
Prowadź CHANGELOG.md w formacie Keep a Changelog i linkuj każde wydanie breaking do przewodnika aktualizacji. SECURITY.md powinien opisywać prywatną drogę zgłaszania oraz okres wsparcia; nigdy nie proś zgłaszających o ujawnienie podatności w publicznym issue. Wersjonowana dokumentacja chroni przed mieszaniem aktualnej konfiguracji ze starym wydaniem major.
Dziel -core od adapterów frameworka wyłącznie wtedy, gdy biblioteka domenowa ma rzeczywistych użytkowników spoza Laravela albo zależności Laravel czynią kontrakt niezręcznym. Przedwczesny podział podwaja wydania, testy i wsparcie. Jasny pojedynczy pakiet jest zwykle bardziej hojnym API.
README to ścieżka wdrożenia, nie katalog klas
Użyjmy konkretnego przykładu: `laravel-webhook-tap` odbiera zweryfikowane dostarczenia webhooków i zapisuje je do późniejszej inspekcji. W pierwszej minucie po `composer require` czytelnik powinien wiedzieć, jakie są wymagania, który sekret ustawić, czy trzeba uruchomić migracje i jak rozpoznać sukces. Architektura, historia zmian i zaawansowane punkty rozszerzenia mogą poczekać do chwili, gdy podstawowa ścieżka zadziała. Niejasna instrukcja instalacji tworzy błędną konfigurację produkcyjną, a później zgłoszenia do autora pakietu.
```md
Requirements
- PHP 8.3 or newer
- Laravel 11, 12 or 13
Install
```bash composer require dominik-dev/laravel-webhook-tap php artisan vendor:publish --tag=webhook-tap-config php artisan migrate ```
Set `WEBHOOK_TAP_SECRET` in `.env`, then add the route shown below. ```
Kolejność poleceń jest częścią kontraktu. Opublikowanie konfiguracji przed pokazaniem trasy mówi, skąd bierze się sekret. Jeżeli pakiet posiada tabelę, `migrate` musi być w instrukcji; pominięcie polecenia nie czyni migracji bezpieczną, tylko przesuwa awarię na pierwsze żądanie. Jeżeli migracje są ładowane automatycznie, napisz to wyraźnie i nie każ użytkownikowi publikować zbędnych plików.
Następnie pokaż jedną kompletną trasę, bez ukrytych importów i magicznego middleware. Nie wolno jednak uniwersalnie nakazywać wyłączenia CSRF: granica między middleware `web` i `api` jest decyzją aplikacji. Udokumentuj wymaganą własność — endpoint dostawcy musi przyjmować jego żądania i być limitowany w odpowiedniej granicy.
```php