> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Laravel Package Skeleton — template starter per pacchetti ufficiali

> Indagine iniziale su laravel/package-skeleton. Template starter ufficiale che raccoglie le best practice per lo sviluppo di pacchetti Laravel. Configurazione completa con Pest, Larastan, Pint, Workbench e CI GitHub Actions.

<Info>
  Questo articolo si basa su un'indagine del codice sorgente. Al momento (luglio 2026) il repository è in fase di sviluppo.
</Info>

## Cos'è Laravel Package Skeleton

[Laravel Package Skeleton](https://github.com/laravel/package-skeleton) è un template starter per creare pacchetti Laravel.

```bash theme={null}
git clone https://github.com/laravel/package-skeleton.git my-package
cd my-package
composer install
```

Eseguendo `composer install` parte automaticamente uno script di configurazione interattivo (`configure.php`), che imposta con un'unica sessione a domande e risposte nome pacchetto, vendor, namespace e funzionalità da usare. Dopo la configurazione sei pronto per iniziare a sviluppare immediatamente.

```mermaid theme={null}
graph TD
    A["Su GitHub, clicca<br>Use this template"] --> B["composer install"]
    B --> C["configure.php parte in automatico"]
    C --> D{"Configurazione interattiva"}
    D --> E["Nome pacchetto, vendor, namespace"]
    D --> F["Seleziona le funzionalità"]
    E --> G["Configurazione completata"]
    F --> G
    G --> H["Verifica il funzionamento con composer test"]
```

## Perché serve questo skeleton

Se inizi a costruire un pacchetto Laravel "a modo tuo", perdi molto tempo in attività non correlate alla logica vera e propria del pacchetto: setup dell'ambiente di test, analisi statica, formattazione del codice, configurazione di GitHub Actions.

Laravel Package Skeleton raccoglie in un unico template le best practice usate dal team di Laravel nello sviluppo reale dei pacchetti. Usando il template puoi saltare la "costruzione dell'ambiente" e iniziare subito dall'implementazione della logica.

## Strumenti inclusi

| Strumento                                                | Ruolo                          |
| -------------------------------------------------------- | ------------------------------ |
| [Pest](https://pestphp.com/)                             | Framework di test              |
| [Larastan](https://github.com/larastan/larastan)         | Analisi statica per Laravel    |
| [Pint](https://laravel.com/docs/pint)                    | Formatter di codice            |
| [Orchestra Testbench](https://packages.tools/testbench/) | Ambiente di test per pacchetti |
| Workbench                                                | App per lo sviluppo end-to-end |

## Funzionalità di pacchetto configurabili

Nel prompt durante `composer install` puoi selezionare solo le funzionalità che ti servono. Gli scaffold relativi alle funzionalità non selezionate vengono rimossi.

| Funzionalità | Descrizione                                     |
| ------------ | ----------------------------------------------- |
| Config file  | Aggiunge un file di configurazione in `config/` |
| Routes       | Aggiunge un file di rotte                       |
| Views        | Aggiunge view Blade                             |
| Translations | Aggiunge file di lingua                         |
| Migrations   | Aggiunge file di migration                      |
| Assets       | Aggiunge asset pubblici                         |
| Commands     | Aggiunge comandi Artisan                        |
| Facade       | Aggiunge una classe facade                      |
| Boost Skill  | Aggiunge skill per agenti AI                    |

## Strumenti configurabili

Come per le funzionalità, in base al progetto puoi anche attivare/disattivare gli strumenti.

| Strumento       | Descrizione                                           |
| --------------- | ----------------------------------------------------- |
| Dependabot      | PR di aggiornamento automatico delle dipendenze       |
| Issue Template  | Template per le issue di GitHub                       |
| Changelog       | Aggiornamento automatico di CHANGELOG.md alla release |
| Funding         | Link ai GitHub Sponsors                               |
| Security Policy | Policy di segnalazione vulnerabilità di sicurezza     |

## Flusso di setup

<Steps>
  <Step title="Crea un repository dal template">
    Premi il pulsante **Use this template** su GitHub per creare un nuovo repository, oppure clona direttamente.

    ```bash theme={null}
    git clone https://github.com/laravel/package-skeleton.git my-package
    cd my-package
    ```
  </Step>

  <Step title="Installa le dipendenze">
    Eseguendo `composer install` parte automaticamente `configure.php`.

    ```bash theme={null}
    composer install
    ```

    Se vuoi eseguire manualmente lo script, usa l'opzione `--no-scripts`.

    ```bash theme={null}
    composer install --no-scripts
    php configure.php
    ```
  </Step>

  <Step title="Rispondi al prompt">
    Le voci seguenti vengono impostate a domande e risposte.

    * Nome e email dell'autore
    * Nome del vendor (es. `kawax`)
    * Nome del pacchetto (es. `my-package`)
    * Descrizione del pacchetto
    * Nome della classe (es. `MyPackage`)
    * Selezione multipla delle funzionalità
    * Selezione multipla degli strumenti
    * Creazione automatica del repository GitHub (se `gh` CLI è autenticato)
  </Step>

  <Step title="Verifica il funzionamento">
    ```bash theme={null}
    composer test
    ```

    Esegue tutti i controlli in ordine: PHPStan → Pint → coverage dei tipi → Pest.
  </Step>

  <Step title="Test end-to-end con Workbench">
    ```bash theme={null}
    composer serve
    ```

    Su `http://localhost:8000` si avvia una piccola app Laravel per la verifica del pacchetto.
  </Step>
</Steps>

## Modalità non interattiva

Per il setup da CI o da script usa il flag `--no-interaction`.

```bash theme={null}
php configure.php --no-interaction --config --routes
```

Specificando i flag di funzionalità, vengono incluse solo quelle indicate. Se li ometti, vengono incluse tutte le funzionalità.

## CI GitHub Actions

Il `tests.yml` incluso nello skeleton è una matrix build che esegue i test su più combinazioni di versione PHP, versione Laravel e OS.

```yaml theme={null}
matrix:
  os: [ubuntu-latest, windows-latest]
  php: [8.3, 8.4, 8.5]
  laravel: [12.*, 13.*]
  stability: [prefer-lowest, prefer-stable]
```

Contenuto eseguito in ciascun job:

1. **PHPStan** (`composer analyse`) — analisi statica
2. **Pint** (`composer lint:check`) — check di stile
3. **Type coverage** (`composer test:types`) — verifica del 100% di copertura dei tipi (solo Ubuntu)
4. **Pest** (`composer test:unit`) — test unitari (solo Ubuntu)

## Automazione del Changelog

`update-changelog.yml` aggiorna automaticamente `CHANGELOG.md` in seguito a un release GitHub. `release.yml` classifica i cambiamenti per label delle PR e genera le release note.

Label delle release note:

| Label            | Categoria                      |
| ---------------- | ------------------------------ |
| `breaking`       | Modifiche non retrocompatibili |
| `enhancement`    | Aggiunta di funzionalità       |
| `bug`            | Bug fix                        |
| `documentation`  | Documentazione                 |
| `dependencies`   | Dipendenze                     |
| `maintenance`    | Manutenzione                   |
| `skip-changelog` | Da escludere dal changelog     |

## Cosa fa `configure.php`

`configure.php` è uno script di bootstrap che si esegue una sola volta per la configurazione. Al termine viene rimosso.

```mermaid theme={null}
graph LR
    A["Esecuzione di configure.php"] --> B["Sostituisce i placeholder<br>:vendor_slug/:package_slug<br>:author_name, ecc."]
    B --> C["Elimina i file delle funzionalità non usate"]
    C --> D["README_PACKAGE.md → README.md<br>AGENTS_PACKAGE.md → AGENTS.md"]
    D --> E["Collega CLAUDE.md a AGENTS.md<br>Collega .claude a .agents"]
    E --> F["Rimuove lo script stesso"]
```

## Impostazioni GitHub post-installazione

Impostazioni consigliate dopo l'installazione, come descritto nel README:

* **Review manuale delle PR Dependabot** — non è incluso alcun workflow di auto-merge
* **Creazione delle label delle release note** — `breaking`, `enhancement`, `bug`, `documentation`, `dependencies`, `maintenance`, `skip-changelog`, `duplicate`
* **Protezione del branch `main`** — poiché l'automazione del Changelog fa commit di `CHANGELOG.md` tramite GitHub Actions, occorre regolare le regole di protezione del branch

Non servono secret aggiuntivi al repository. I workflow inclusi usano il `GITHUB_TOKEN` integrato di GitHub.

## Stato attuale dello sviluppo

* **Repository GitHub**: [laravel/package-skeleton](https://github.com/laravel/package-skeleton)
* **Data di pubblicazione**: luglio 2026 (sviluppo attivo)
* **Nota**: essendo in fase iniziale, API e struttura possono cambiare

Se stai per iniziare a sviluppare un pacchetto Laravel, meglio partire da questo template piuttosto che costruire da zero uno skeleton personale. Contiene le best practice raccolte dal team di Laravel in anni di sviluppo di pacchetti.

<Card title="Repository laravel/package-skeleton" icon="github" href="https://github.com/laravel/package-skeleton">
  Codice sorgente e ultime novità qui.
</Card>

<Card title="Documentazione ufficiale sullo sviluppo di pacchetti" icon="book-open" href="https://laravel.com/docs/packages">
  Per le basi dello sviluppo di pacchetti Laravel consulta la documentazione ufficiale.
</Card>


## Related topics

- [Come creare uno starter kit per Laravel](/it/advanced/starter-kit-creation.md)
- [Starter kit](/it/starter-kits.md)
- [Introduzione a Svelte — le basi per usarlo con Inertia × Laravel](/it/blog/svelte-introduction.md)
- [Laravel Chisel — libreria di script post-installazione per starter kit](/it/blog/chisel-introduction.md)
- [Tutorial per bot - Laravel Bluesky](/it/packages/laravel-bluesky/bot-tutorial.md)