diff --git a/README.md b/README.md index 050f1aa..356adc6 100644 --- a/README.md +++ b/README.md @@ -1,107 +1,50 @@ -# Sage Child Theme Support +# Nutshell: Enhanced Acorn Support for WordPress Themes [![Code Style](https://github.com/yardinternet/skeleton-package/actions/workflows/format-php.yml/badge.svg?no-cache)](https://github.com/yardinternet/skeleton-package/actions/workflows/format-php.yml) [![PHPStan](https://github.com/yardinternet/skeleton-package/actions/workflows/phpstan.yml/badge.svg?no-cache)](https://github.com/yardinternet/skeleton-package/actions/workflows/phpstan.yml) - - -Classes to use Acorn with child themes: +**Nutshell** is a feature-rich package designed to extend [Acorn](https://roots.io/acorn/) for WordPress themes. It provides a flexible foundation for advanced theme development, including configuration inheritance, Sentry integration, Vite asset support, and more. -- WP like inheritance for config files; child config will override parent configuration. -- No directory scans, everything is configuration based. +## Features + +- **Child Theme Configuration Inheritance**: + - Allows child themes to override parent configuration files without directory scans. + - Uses a custom configuration repository to support unsetting and merging config values. +- **Vite Asset Support**: + - Integrates with Vite for modern asset bundling and hot reloading. +- **Sentry Integration**: + - Seamless error reporting via Sentry for Laravel. +- **Custom View Composers**: + - Manual registration of view composers for fine-grained control. +- **Custom Console Commands**: + - Register custom Artisan commands via configuration. ## Requirements -- [Acorn](https://github.com/roots/acorn) >= 4.0 +- PHP >= 8.1 +- [Acorn](https://github.com/roots/acorn) ^4.3 +- Composer ## Installation -To install this package using Composer, follow these steps: - -1. Add the following to the `repositories` section of your `composer.json`: - - ```json - { - "type": "vcs", - "url": "git@github.com:yardinternet/sage-child-theme-support.git" - } - ``` +1. Install this package with composer -2. Install this package with Composer: + ```sh + composer require yard/nutshell + ``` - ```sh - composer require yard/sage-child-theme-support - ``` - -## Configuration +2. Ensure your project's `composer.json` uses PSR-4 autoloading for your theme and childtheme and remove any redundant autoloading from the theme itself. -1. Create a child theme with Sage as the parent theme ([How To Create A Child Theme | Wordpress.org](https://developer.wordpress.org/themes/advanced-topics/child-themes/#how-to-create-a-child-theme)) - - Example `style.css`: - - ```css - /** - * Theme Name: Sage Child Theme - * Template: sage - * Theme URI: https://www.example.com/sage-child/ - * Description: Sage child theme - * Version: 1.0.0 - * Author: Example Inc. - * Author URI: http://www.example.com/ - * Text Domain: sage - * License: MIT License - * License URI: https://opensource.org/licenses/MIT - * Requires PHP: 8.1 - * Requires at least: 5.9 - */ - ``` - -2. Add PSR-4 autoloading for your child theme to your (root) `composer.json`: - - ```diff - "autoload": { + ```diff + "autoload": { "psr-4": { - "App\\": "web/app/themes/sage/app/", - + "ChildTheme\\App\\": "web/app/themes/child-theme/app/", + "App\\": "web/app/themes/sage/app/", + + "ChildTheme\\App\\": "web/app/themes/child-theme/app/", } - }, - ``` - - Remove the autoloading from your theme `composer.json` if applicable. - -3. In `sage/config/app.php` change: - - ```diff - -use Roots\Acorn\ServiceProvider; - +use Yard\SageChildThemeSupport\ServiceProvider; - ``` - -4. In `sage/functions.php` change: + }, + ``` - ```diff - -\Roots\bootloader()->boot(); - +define('ACORN_BASEPATH', __DIR__); - +\Yard\SageChildThemeSupport\bootloader()->boot(); - ``` - -5. Add view composers to `config/view.php` - - ```diff - - 'composers' => [], - + 'composers => [ - + 'app' => App\View\Composers\App::class, - + 'comments' => App\View\Composers\Comments::class, - + 'post' => App\View\Composers\Post::class, - + ], - ``` - -6. Add any custom console commands to `config/console.php`: - - ```diff - + 'commands => [ - + 'test' => App\Console\Commands\Test::class, - + ], - ``` +## Configuration > [!IMPORTANT] > After this change: @@ -109,7 +52,75 @@ To install this package using Composer, follow these steps: > - View Composers in the app/View/Composers directory will no longer be loaded automatically. To ensure they are registered, you have to configure them manually. > - Console Commands in the app/Console/Commands directory will no longer be loaded automatically. To ensure they are register, you have to configure them manually. +1. **Child Theme Setup** + - Create a child theme with Sage as the parent theme. See [WordPress Child Themes](https://developer.wordpress.org/themes/advanced-topics/child-themes/#how-to-create-a-child-theme). + + Example `style.css`: + + ```css + /** + * Theme Name: Sage Child Theme + * Template: sage + * Theme URI: https://www.example.com/sage-child/ + * Description: Sage child theme + * Version: 1.0.0 + * Author: Example Inc. + * Author URI: http://www.example.com/ + * Text Domain: sage + * License: MIT License + * License URI: https://opensource.org/licenses/MIT + * Requires PHP: 8.1 + * Requires at least: 5.9 + */ + ``` + + - Place your configuration files in `config/` within your child theme directory. These will be merged with the parent configuration where child theme configuration takes precedence. To unset a configuration option from the parent theme in the child theme you can pass an empty array for that configuration option. + +2. **Update Acorn Bootloader** + + - In your theme's `functions.php`, use the `Yard\Nutshell\bootloader()` helper to bootstrap Acorn with Nutshell's enhancements. + + ```diff + -\Roots\bootloader()->boot(); + +define('ACORN_BASEPATH', __DIR__); + +\Yard\Nutshell\bootloader()->boot(); + ``` + +3. **Register View Composers** + - Add your view composers to `config/view.php` under the `composers` key. Automatic discovery is disabled for explicit control. + + ```diff + - 'composers' => [], + + 'composers => [ + + 'app' => App\View\Composers\App::class, + + 'comments' => App\View\Composers\Comments::class, + + 'post' => App\View\Composers\Post::class, + + ], + ``` + +4. **Register Console Commands** + - Add custom Artisan commands to `config/console.php` under the `commands` key. + + ```diff + + 'commands => [ + + 'test' => App\Console\Commands\Test::class, + + ], + ``` + +5. **Vite Integration** + - Vite is enabled by default. Use the provided `Yard\Nutshell\Assets\Vite` class for asset management. + +6. **Sentry Integration** + - Sentry is automatically integrated if `sentry/sentry-laravel` is installed and configured. + ## Usage -To override configuration for your child theme add the relevant files to the `child-theme/config` directory. -The configuration for the child theme is merged with the parent configuration where child theme configuration takes precedence. To unset a configuration option from the parent theme in the child theme you can pass an empty array for that configuration option. +- **Configuration Inheritance**: Any config file in your child theme's `config/` directory will override the parent. Empty config files will unset the corresponding configuration. +- **View Composers**: Register all composers manually in `config/view.php`. +- **Console Commands**: Register all commands manually in `config/console.php`. +- **Vite**: Use the `@vite` directive or helper as usual; Nutshell ensures correct asset paths. +- **Sentry**: Errors and exceptions are reported to Sentry automatically. + +## Contributing + +Pull requests are welcome! Please ensure code style and tests pass before submitting. diff --git a/composer.json b/composer.json index 39fd92a..938e39b 100644 --- a/composer.json +++ b/composer.json @@ -1,5 +1,5 @@ { - "name": "yard/sage-child-theme-support", + "name": "yard/nutshell", "type": "package", "description": "Package to enable Acorn in child themes", "license": "MIT", @@ -22,7 +22,7 @@ }, "autoload": { "psr-4": { - "Yard\\SageChildThemeSupport\\": "src/" + "Yard\\Nutshell\\": "src/" }, "files": [ "src/helpers.php" diff --git a/src/Assets/Vite.php b/src/Assets/Vite.php index ac20962..924cbe8 100644 --- a/src/Assets/Vite.php +++ b/src/Assets/Vite.php @@ -2,7 +2,7 @@ declare(strict_types=1); -namespace Yard\SageChildThemeSupport\Assets; +namespace Yard\Nutshell\Assets; use Illuminate\Foundation\Vite as FoundationVite; diff --git a/src/Bootstrap/LoadConfiguration.php b/src/Bootstrap/LoadConfiguration.php index 93ef578..6f19d68 100644 --- a/src/Bootstrap/LoadConfiguration.php +++ b/src/Bootstrap/LoadConfiguration.php @@ -2,12 +2,12 @@ declare(strict_types=1); -namespace Yard\SageChildThemeSupport\Bootstrap; +namespace Yard\Nutshell\Bootstrap; use Illuminate\Contracts\Foundation\Application as ApplicationContract; use Illuminate\Foundation\Application; use Roots\Acorn\Bootstrap\LoadConfiguration as AcornLoadConfiguration; -use Yard\SageChildThemeSupport\Config\Repository; +use Yard\Nutshell\Config\Repository; class LoadConfiguration extends AcornLoadConfiguration { diff --git a/src/Config/Repository.php b/src/Config/Repository.php index 5f33af6..2d3738d 100644 --- a/src/Config/Repository.php +++ b/src/Config/Repository.php @@ -2,7 +2,7 @@ declare(strict_types=1); -namespace Yard\SageChildThemeSupport\Config; +namespace Yard\Nutshell\Config; use Illuminate\Config\Repository as RepositoryBase; use Illuminate\Support\Arr; diff --git a/src/Console/Kernel.php b/src/Console/Kernel.php index 5a883a4..0dfc0d2 100644 --- a/src/Console/Kernel.php +++ b/src/Console/Kernel.php @@ -2,7 +2,7 @@ declare(strict_types=1); -namespace Yard\SageChildThemeSupport\Console; +namespace Yard\Nutshell\Console; use Roots\Acorn\Console\Kernel as AcornKernel; diff --git a/src/DefaultProviders.php b/src/DefaultProviders.php index 09b003b..d553853 100644 --- a/src/DefaultProviders.php +++ b/src/DefaultProviders.php @@ -2,7 +2,7 @@ declare(strict_types=1); -namespace Yard\SageChildThemeSupport; +namespace Yard\Nutshell; use Roots\Acorn\DefaultProviders as AcornDefaultProviders; @@ -12,7 +12,7 @@ class DefaultProviders extends AcornDefaultProviders * @var array */ protected array $acornProvidersReplacements = [ - \Roots\Acorn\View\ViewServiceProvider::class => \Yard\SageChildThemeSupport\View\ViewServiceProvider::class, + \Roots\Acorn\View\ViewServiceProvider::class => \Yard\Nutshell\View\ViewServiceProvider::class, ]; /** diff --git a/src/Exceptions/Handler.php b/src/Exceptions/Handler.php index 6e016c0..5a5bbc4 100644 --- a/src/Exceptions/Handler.php +++ b/src/Exceptions/Handler.php @@ -2,7 +2,7 @@ declare(strict_types=1); -namespace Yard\SageChildThemeSupport\Exceptions; +namespace Yard\Nutshell\Exceptions; use Roots\Acorn\Exceptions\Handler as AcornHandler; use Sentry\Laravel\Integration; diff --git a/src/ServiceProvider.php b/src/ServiceProvider.php index 25fa7fb..f240151 100644 --- a/src/ServiceProvider.php +++ b/src/ServiceProvider.php @@ -2,7 +2,7 @@ declare(strict_types=1); -namespace Yard\SageChildThemeSupport; +namespace Yard\Nutshell; use Illuminate\Support\ServiceProvider as ServiceProviderBase; diff --git a/src/View/ViewServiceProvider.php b/src/View/ViewServiceProvider.php index efab21f..14317de 100644 --- a/src/View/ViewServiceProvider.php +++ b/src/View/ViewServiceProvider.php @@ -2,7 +2,7 @@ declare(strict_types=1); -namespace Yard\SageChildThemeSupport\View; +namespace Yard\Nutshell\View; use Illuminate\Support\Arr; use Roots\Acorn\View\Composer; diff --git a/src/helpers.php b/src/helpers.php index 70c0628..ec71471 100644 --- a/src/helpers.php +++ b/src/helpers.php @@ -2,7 +2,7 @@ declare(strict_types=1); -namespace Yard\SageChildThemeSupport; +namespace Yard\Nutshell; use Roots\Acorn\Bootloader; @@ -12,21 +12,21 @@ function bootloader(): Bootloader $bootloader->getApplication()->bind( \Roots\Acorn\Bootstrap\LoadConfiguration::class, - \Yard\SageChildThemeSupport\Bootstrap\LoadConfiguration::class + \Yard\Nutshell\Bootstrap\LoadConfiguration::class ); $bootloader->getApplication()->bind( \Roots\Acorn\Console\Kernel::class, - \Yard\SageChildThemeSupport\Console\Kernel::class + \Yard\Nutshell\Console\Kernel::class ); $bootloader->getApplication()->bind( \Roots\Acorn\Exceptions\Handler::class, - \Yard\SageChildThemeSupport\Exceptions\Handler::class + \Yard\Nutshell\Exceptions\Handler::class ); $bootloader->getApplication()->alias( - \Yard\SageChildThemeSupport\Assets\Vite::class, + \Yard\Nutshell\Assets\Vite::class, \Illuminate\Foundation\Vite::class );