spatie-package-skeleton

Creating a Laravel Package with Spatie's Skeleton

Prerequisites

• gh CLI installed and authenticated
• php available in PATH
• composer available in PATH

Workflow

1. Gather Package Details

Ask the user for:

• Vendor name (e.g. spatie) — the GitHub org or username
• Package name (e.g. laravel-cool-feature) — the repo/package name
• Package description — one-liner for composer.json
• Visibility — public or private (default: public)

Use defaults where sensible:

• Author name: from git config user.name
• Author email: from git config user.email
• Author username: from gh auth status
• Vendor namespace: PascalCase of vendor name (e.g. Spatie)
• Class name: TitleCase of package name without laravel- prefix (e.g. CoolFeature)

2. Create the Repository from Template

gh repo create <vendor>/<package-name> --template spatie/package-skeleton-laravel --public --clone
cd <package-name>

If the user wants a private repo, use --private instead of --public.

3. Configure the Package (Manual Replacement)

WARNING: Do NOT pipe stdin to configure.php. The script's child processes (gh auth status, git log, git config) consume lines from the piped stdin, causing inputs to shift and produce garbled results. Instead, do the replacements manually:

1. Run sed to replace all placeholder strings across the repo:

find . -type f -not -path './.git/*' -not -path './vendor/*' -not -name 'configure.php' -exec sed -i '' \
  -e 's/:author_name/Author Name/g' \
  -e 's/:author_username/authorusername/g' \
  -e 's/author@domain\.com/[email protected]/g' \
  -e 's/:vendor_name/Vendor Name/g' \
  -e 's/:vendor_slug/vendorslug/g' \
  -e 's/VendorName/VendorNamespace/g' \
  -e 's/:package_slug_without_prefix/package-without-prefix/g' \
  -e 's/:package_slug/package-name/g' \
  -e 's/:package_name/package-name/g' \
  -e 's/:package_description/Package description here/g' \
  -e 's/Skeleton/ClassName/g' \
  -e 's/skeleton/package-name/g' \
  -e 's/migration_table_name/package_without_prefix/g' \
  -e 's/variable/variableName/g' \
  {} +

Important: The order of -e flags matters. Replace :package_slug_without_prefix before :package_slug to avoid partial matches. Replace Skeleton (PascalCase) before skeleton (lowercase).

2. Rename the skeleton files:

mv src/Skeleton.php src/ClassName.php
mv src/SkeletonServiceProvider.php src/ClassNameServiceProvider.php
mv src/Facades/Skeleton.php src/Facades/ClassName.php
mv src/Commands/SkeletonCommand.php src/Commands/ClassNameCommand.php
mv config/skeleton.php config/package-without-prefix.php
mv database/migrations/create_skeleton_table.php.stub database/migrations/create_package_without_prefix_table.php.stub

3. Delete configure.php and run composer install:

rm configure.php
composer install

Use a longer timeout (5 minutes) for composer install.

4. Verify Setup

After the script completes:

# Check the directory structure
ls -la src/
# Verify composer.json looks correct
cat composer.json | head -20
# Check tests passed during setup

5. Initial Commit and Push

The configure script modifies all files but doesn't commit. Create the initial commit:

git add -A
git commit -m "Configure package skeleton"
git push -u origin main

6. Report to User

Tell the user:

• The repo URL (e.g. https://github.com/<vendor>/<package-name>)
• The namespace (e.g. VendorNamespace\ClassName)
• Key files to start editing:
  • src/<ClassName>.php — main package class
  • src/<ClassName>ServiceProvider.php — service provider
  • config/<package-slug>.php — configuration
  • tests/ — test directory

Detailed references

Load these as needed:

• Post-setup reference: references/post-setup.md. What the skeleton generated and what to do with it.
• Package patterns: references/package-patterns.md. API design principles, and proven extensibility patterns (events, configurable models and jobs, action classes) instead of config option creep.