Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
126 | 127 | Skip » 128 | 129 |
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
126 | 127 | Skip » 128 | 129 |Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
270 | 271 | Skip » 272 | ``` 273 | 274 | We reduced PHP logic duplication, but this doesn't solve the use case where we want to have that variable available in a view partial, for example. For this we can use the `\App::render( $view, $context = [] )` function which works very similarly to `get_template_part()` but as you can see it has an optional argument which allows you to pass context variables as well: 275 | ```php 276 | $skip_url] ); ?> 277 | ``` 278 | 279 | ## FAQ 280 | 281 | ##### What if we wish to have a partial that is reused throughout the site but it needs a certain variable? Do we have to add that logic to every controller which loads a view which includes that partial? 282 | 283 | Thankfully, no! This is where view composers come into play - check out the [View Composers](/framework/views/view-composers) article to see how they can solve this problem and more. 284 | 285 | ##### What if we wanted to show the CTA on a page other than the homepage - do we have to hardcode that page's URL in the route definition? 286 | 287 | We can but we don't have to. We can take advantage of WP Emerge's dynamic [Route Conditions](/framework/routing/conditions). As an example, this is what our route definition will look like if we wish to show the CTA on any page that uses a custom template called `template-cta-enabled-page.php`: 288 | ```php 289 | \App::route()->get() 290 | ->where( 'post_template', 'template-cta-enabled-page.php' ) 291 | ->handle( 'HomeController@index' ); 292 | ``` 293 | -------------------------------------------------------------------------------- /framework/_sidebar.md: -------------------------------------------------------------------------------- 1 | * Framework 2 | 3 | * [Overview](/framework/overview) 4 | * [Quickstart](/framework/quickstart) 5 | * [Configuration](/framework/configuration) 6 | * [0 to 100 Setup](/framework/0-to-100-setup) 7 | 8 | * Routing 9 | 10 | * [Request Lifecycle](/framework/routing/request-lifecycle) 11 | * [Defining Routes](/framework/routing/defining-routes) 12 | * [Methods](/framework/routing/methods) 13 | * [Conditions](/framework/routing/conditions) 14 | * [Groups](/framework/routing/groups) 15 | * [Handlers](/framework/routing/handlers) 16 | * [Controllers](/framework/routing/controllers) 17 | * [Middleware](/framework/routing/middleware) 18 | * [Error Handling](/framework/routing/error-handling) 19 | 20 | * Views 21 | 22 | * [Overview](/framework/views/overview) 23 | * [Layouts](/framework/views/layouts) 24 | * [Global Context](/framework/views/global-context) 25 | * [View Composers](/framework/views/view-composers) 26 | 27 | * Tools 28 | 29 | * [\App shortcuts](/framework/tools/app-shortcuts) 30 | * [Service Providers](/framework/tools/service-providers) 31 | * [Flash](/framework/tools/flash) 32 | * [OldInput](/framework/tools/oldinput) 33 | * [CSRF Protection](/framework/tools/csrf-protection) 34 | 35 | * Extending 36 | 37 | * [Overview](/framework/extending/overview) 38 | -------------------------------------------------------------------------------- /framework/configuration.md: -------------------------------------------------------------------------------- 1 | # Configuration 2 | 3 | When booting WP Emerge you can specify a number of configuration options: 4 | ```php 5 | \App::make()->bootstrap( [ 6 | /** 7 | * Default class namespace prefix. 8 | * Automatically prepended to all controllers and view composers for convenience. 9 | */ 10 | 'namespace' => 'App\\', 11 | 12 | /** 13 | * Array of service providers you wish to enable. 14 | */ 15 | 'providers' => [ 16 | // Examples: 17 | MyServiceProviders::class, 18 | // Blade example for htmlburger/wpemerge-blade: 19 | WPEmergeBlade\View\ServiceProvider::class, 20 | ], 21 | 22 | /** 23 | * Array of route group definitions and default attributes. 24 | * All of these are optional so if we are not using 25 | * a certain group of routes we can skip it. 26 | * If we are not using routing at all we can skip 27 | * the entire 'routes' option. 28 | */ 29 | 'routes' => [ 30 | 'web' => [ 31 | 'definitions' => get_template_directory() . '/routes/web.php', 32 | 'attributes' => [], 33 | ], 34 | 'admin' => [ 35 | 'definitions' => get_template_directory() . '/routes/admin.php', 36 | 'attributes' => [], 37 | ], 38 | 'ajax' => [ 39 | 'definitions' => get_template_directory() . '/routes/ajax.php', 40 | 'attributes' => [], 41 | ], 42 | ], 43 | 44 | /** 45 | * Register middleware class aliases. 46 | * Use fully qualified middleware class names. 47 | * 48 | * Internal aliases that you should avoid overriding: 49 | * - 'flash' 50 | * - 'old_input' 51 | * - 'csrf' 52 | * - 'user.logged_in' 53 | * - 'user.logged_out' 54 | * - 'user.can' 55 | */ 56 | 'middleware' => [ 57 | // Examples: 58 | 'mymiddleware' => \App\Middleware\MyMiddleware::class, 59 | ], 60 | 61 | /** 62 | * Register middleware groups. 63 | * Use fully qualified middleware class names or registered aliases. 64 | * There are a couple built-in groups that you may override: 65 | * - 'web' - Automatically applied to web routes. 66 | * - 'admin' - Automatically applied to admin routes. 67 | * - 'ajax' - Automatically applied to ajax routes. 68 | * - 'global' - Automatically applied to all of the above. 69 | * - 'wpemerge' - Internal group applied the same way 'global' is. 70 | * 71 | * Warning: The 'wpemerge' group contains some internal WP Emerge 72 | * middleware which you should avoid overriding. 73 | */ 74 | 'middleware_groups' => [ 75 | 'global' => [], 76 | 'web' => [ 77 | // Examples: 78 | 'mymiddleware', 79 | ], 80 | 'ajax' => [], 81 | 'admin' => [], 82 | ], 83 | 84 | /** 85 | * Optionally specify middleware execution order. 86 | * Use fully qualified middleware class names. 87 | * Middlewares not in this list will execute after all middlewares in 88 | * it in the order they were assigned. 89 | */ 90 | 'middleware_priority' => [ 91 | // Examples: 92 | \App\Middleware\MyMiddlewareThatShouldRunFirst::class, 93 | \App\Middleware\MyMiddlewareThatShouldRunSecond::class, 94 | ], 95 | 96 | /** 97 | * Custom directories to search for views. 98 | * Use absolute paths or leave blank to disable. 99 | * View engines other than the default PhpViewEngine 100 | * will default to this value as well but may have 101 | * their own setting as well. 102 | */ 103 | 'views' => [get_stylesheet_directory(), get_template_directory()], 104 | 105 | /** 106 | * View Composers settings. 107 | */ 108 | 'view_composers' => [ 109 | // Default namespace. 110 | 'namespace' => 'App\\ViewComposers\\', 111 | ], 112 | 113 | /** 114 | * Cache settings. 115 | */ 116 | 'cache' => [ 117 | // Absolute path to custom default cache directory. 118 | // Extensions like Blade and Twig will use this value for their views cache 119 | // unless one has been specified for them. 120 | // Defaults to ROOT_DIR/wp-content/uploads/wpemerge/cache. 121 | 'path' =>'/some/cache/directory/', 122 | ], 123 | 124 | /** 125 | * Debug settings. 126 | */ 127 | 'debug' => [ 128 | // Enable debug mode. Defaults to the value of WP_DEBUG. 129 | 'enable' => true, 130 | // Enable the use of filp/whoops for an enhanced error interface. Defaults to true. 131 | 'pretty_errors' => true, 132 | ], 133 | ] ) 134 | ``` 135 | -------------------------------------------------------------------------------- /framework/extending/overview.md: -------------------------------------------------------------------------------- 1 | # Extending 2 | 3 | WP Emerge uses a service container for all of its dependencies which means that you can easily replace or add dependencies. 4 | For a real-world example, we will be adding our own custom routing condition. 5 | 6 | ## Scenario 7 | 8 | - Our site has events with a post type of `event`. 9 | - Events have an `event_date` post meta which holds the date the event is scheduled for. The date format stored is 10 | `Y-m-d` e.g. 2018-12-31. 11 | - Our goal is to match all past events and display a custom page. 12 | 13 | ## Implementation 14 | 15 | 1. First, we will define our custom condition class: 16 | ```php 17 | use WPEmerge\Requests\RequestInterface; 18 | use WPEmerge\Routing\Conditions\ConditionInterface; 19 | 20 | class PastEvent implements ConditionInterface { 21 | public function isSatisfied( RequestInterface $request ) { 22 | // Makre sure we are on a singular event page. 23 | if ( is_singular( 'event' ) ) { 24 | // Get the event date. 25 | $event_date = get_post_meta( get_the_ID(), 'event_date', true ); 26 | // Get today's date in the same format. 27 | $today = date( 'Y-m-d' ); 28 | 29 | // The Y-m-d format is very easy to compare. 30 | if ( $today > $event_date ) { 31 | // Our condition is satisfied - we must return true. 32 | return true; 33 | } 34 | } 35 | 36 | // In all other cases return false. 37 | return false; 38 | } 39 | 40 | public function getArguments( RequestInterface $request ) { 41 | // We can return an array of arguments we wish to pass on to the 42 | // route handler for convenience. 43 | // We do not really need to pass anything so we return an empty 44 | // array but we could pass the event date, for example. 45 | return []; 46 | } 47 | } 48 | ``` 49 | 50 | 2. Next, we will define a service provider class which will register our new condition: 51 | ```php 52 | use WPEmerge\ServiceProviders\ServiceProviderInterface; 53 | 54 | class PastEventConditionServiceProvider implements ServiceProviderInterface { 55 | public function register( $container ) { 56 | // Conditions are registered by appending them to the 57 | // array of condition types which is registered with 58 | // the WPEMERGE_ROUTING_CONDITION_TYPES_KEY key 59 | // in the container. 60 | $condition_name = 'past_event'; 61 | $condition_class = PastEvent::class; 62 | 63 | $container[ WPEMERGE_ROUTING_CONDITION_TYPES_KEY ] = array_merge( 64 | $container[ WPEMERGE_ROUTING_CONDITION_TYPES_KEY ], 65 | [ 66 | $condition_name => $condition_class, 67 | ] 68 | ); 69 | } 70 | 71 | public function bootstrap( $container ) { 72 | // We have nothing to bootstrap. 73 | } 74 | } 75 | ``` 76 | 77 | 3. Finally, we pass our brand new service provider while booting WP Emerge: 78 | ```php 79 | \App::make()->bootstrap( [ 80 | 'providers' => [ 81 | // ... other providers go here 82 | PastEventConditionServiceProvider::class, 83 | // ... or here 84 | ], 85 | // ... other options go here 86 | ] ); 87 | ``` 88 | 89 | We can now use our custom route condition like so: 90 | ```php 91 | \App::route()->get() 92 | ->where( 'past_event' ) 93 | ->handle( function( $request ) { 94 | return 'This event has already passed :('; 95 | } ); 96 | ``` 97 | -------------------------------------------------------------------------------- /framework/overview.md: -------------------------------------------------------------------------------- 1 | #
2 |
3 | [](https://packagist.org/packages/htmlburger/wpemerge) [](https://github.com/htmlburger/wpemerge/actions/workflows/phpunit.yml) [](https://scrutinizer-ci.com/g/htmlburger/wpemerge/) [](https://scrutinizer-ci.com/g/htmlburger/wpemerge/code-structure/master/code-coverage) [](https://gitter.im/wpemerge/Lobby)
4 |
5 |
6 | 📦 A micro framework which modernizes WordPress as a CMS development by providing tools to implement MVC and more.
7 |
8 | 🔥 Integration is incremental - you can use it only on the pages you want or on all pages.
9 |
10 | ❤ If you've used frameworks such as Laravel, Slim or Symfony you will love WP Emerge.
11 |
12 | 🚀 Also, make sure you check out the WP Emerge [Starter Plugin](https://github.com/htmlburger/wpemerge-plugin) and [Starter Theme](https://github.com/htmlburger/wpemerge-theme) projects.
13 |
14 | ## Summary
15 |
16 | - [Documentation](#documentation)
17 | - [API Reference](#api-reference)
18 | - [Development Team](#development-team)
19 | - [Comparison Table](#comparison-table-¹-²)
20 | - [Non-goals](#non-goals)
21 | - [Requirements](#requirements)
22 | - [Features](#features)
23 | - [Contributing](#contributing)
24 |
25 | ## Documentation
26 |
27 | [http://docs.wpemerge.com/#/framework/overview](http://docs.wpemerge.com/#/framework/overview)
28 |
29 | [http://docs.wpemerge.com/#/framework/quickstart](http://docs.wpemerge.com/#/framework/quickstart)
30 |
31 | ## API Reference
32 |
33 | [https://api.wpemerge.com/](https://api.wpemerge.com/)
34 |
35 | ## Development Team
36 |
37 | Brought to you by [Atanas Angelov](https://atanas.dev/) and the lovely folks at [htmlBurger](http://htmlburger.com).
38 |
39 | ## Comparison Table ¹ ²
40 |
41 | | | WPEmerge | Sage | Timber |
42 | | --- | --- | --- | --- |
43 | | View Engine | PHP, Blade, Twig, any | PHP, Blade | Twig |
44 | | Routing | ✔ | ✖ | ✔ |
45 | | WP Admin Routing | ✔ | ✖ | ✖ |
46 | | WP AJAX Routing | ✔ | ✖ | ✖ |
47 | | MVC | ✖✔✔ | ✖✔✖³ | ✖✔✖ |
48 | | Middleware | ✔ | ✖ | ✖ |
49 | | View Composers | ✔ | ✔/✖⁴ | ✖ |
50 | | Service Container | ✔ | ✔ | ✖ |
51 | | [Advanced Error Reporting](/framework/routing/error-handling) | ✔ | ✖ | ✖ |
52 |
53 | _¹ We are comparing frameworks and themes - style, build tools etc. are not mentioned. For a full comparison check out the [WP Emerge Starter Theme](/starter/theme/overview)._
54 |
55 | _² WP Emerge is theme agnostic - you can use it in any theme._
56 |
57 | _³ Sage's Controller is more of a View Composer than a Controller._
58 |
59 | _⁴ Sage's Controller provides similar functionality but is limited to 1 composer (controller) per view and vice versa._
60 |
61 | _Email any factual inaccuracies to [hi@atanas.dev](mailto:hi@atanas.dev) so they can be corrected._
62 |
63 | ## Non-goals
64 |
65 | - Taking over the WordPress main query.
66 |
67 | WP Emerge does __not__ take over the main query - it actively works with it.
68 | - Taking over WordPress routing.
69 |
70 | WP Emerge does __not__ take over WordPress' routing - it actively works with it. The only exception to this are hardcoded URLs explicitly added by a user.
71 | - Reinventing WordPress APIs using object-oriented interfaces.
72 |
73 | WP Emerge does not provide alternative APIs for registering post types, taxonomies or the like for little added benefit. Instead, it provides logical and handy places for developers to use core APIs.
74 | - Using a third party engine by default.
75 |
76 | WP Emerge uses PHP by default in the same way WordPress does but with added features. Using a third party engine is entirely optional and requires installing an extension.
77 | - Include most of Laravel or another framework.
78 |
79 | WP Emerge is lean and tuned for WordPress. While inspired by Laravel, it does not come with any `illuminate/*` packages. There are only 2 third party production dependencies:
80 | - `pimple/pimple` - The single-file PHP service container.
81 | - `guzzlehttp/psr7` - A PSR-7 Request and ServerRequest implementation.
82 |
83 | ## Requirements
84 |
85 | - [PHP](http://php.net/) >= 5.5
86 | - [WordPress](https://wordpress.org/) >= 4.7
87 | - [Composer](https://getcomposer.org/)
88 |
89 | ## Features
90 |
91 | #### Named routes with custom URLs or dynamic conditions
92 |
93 | ```php
94 | \App::route()->get()->url( '/' )->handle( 'HomeController@index' );
95 |
96 | \App::route()->get()
97 | ->url( '/custom' )
98 | ->query( function ( $query_vars ) {
99 | return [
100 | // WP_Query query vars go here ...
101 | ];
102 | } )
103 | ->handle( 'CustomController@custom' );
104 |
105 | \App::route()->get()
106 | ->where( 'post_id', get_option( 'page_on_front' ) )
107 | ->handle( 'HomeController@index' );
108 |
109 | \App::route()->get()
110 | ->where( function() {
111 | return is_front_page();
112 | } );
113 | ->handle( 'HomeController@index' );
114 | ```
115 |
116 | - Enable the use of controllers to compartmentalize your business logic away from your presentation.
117 | - Use existing routes or add new ones.
118 | - Use built-in dynamic route conditions or define your own custom ones.
119 | - Use anonymous functions for quick one-off conditions.
120 | - Use `\App::routeUrl()` to get the URL of a named route to avoid hard-coding URLs.
121 |
122 | ---
123 |
124 | #### Controllers
125 |
126 | ```php
127 | class HomeController {
128 | public function index( $request ) {
129 | $name = $request->query( 'name' );
130 | return \App::view( 'templates/home.php' )
131 | ->with( [
132 | 'welcome' => 'Welcome, ' . $name . '!',
133 | ] );
134 | }
135 | }
136 | ```
137 |
138 | - Separate unrelated business logic into controllers, and related business logic into controller methods.
139 | - Receive an object representing the current request and respond with a PSR-7 response.
140 | - Use different methods for different routes.
141 | - Respond with a view, json, a redirect etc.
142 | - Easy to test.
143 |
144 | ---
145 |
146 | #### Middleware
147 |
148 | ```php
149 | \App::route()->get()
150 | ->url( '/' )
151 | ->middleware( ['user.can:manage_options', 'minify'] )
152 | ->handle( 'HomeController@index' );
153 | ```
154 |
155 | - Hook before and/or after controller methods.
156 | - Add globally or to specific routes or route groups.
157 | - Powers features such as Flash and OldInput.
158 |
159 | ---
160 |
161 | #### [PSR-7](http://www.php-fig.org/psr/psr-7/) Responses
162 |
163 | ```php
164 | class HomeController {
165 | public function index( $request ) {
166 | return \App::response()
167 | ->withHeader( 'X-Custom-Header', 'foo' );
168 | }
169 | }
170 | ```
171 |
172 | - Use PSR-7 objects for your responses.
173 | - Easy to stream and modify before outputting.
174 | - Uses Guzzle's implementation - [read more](https://github.com/guzzle/psr7).
175 |
176 | ---
177 |
178 | #### View Composers
179 |
180 | ```php
181 | \App::views()->addComposer( 'templates/about-us', function( $view ) {
182 | $view->with( ['hello' => 'world'] );
183 | } );
184 | ```
185 |
186 | - Pass generic context to partials regardless of which controller or parent view uses them.
187 | - Work with any View engine (Php, Blade, Twig).
188 |
189 | ---
190 |
191 | #### Service container
192 |
193 | ```php
194 | // Run this inside the register() method of a service provider.
195 | $container['my_service'] = function( $container ) {
196 | return new MyService( $container['my_dependency'] );
197 | };
198 | ```
199 |
200 | - Define your dependencies in a service container.
201 | - Override any and all WP Emerge dependencies when needed.
202 | - Enables dependency injection.
203 | - Uses Pimple - [read more](https://pimple.symfony.com/).
204 |
205 | ---
206 |
207 | #### Service providers
208 |
209 | ```php
210 | class MyServiceProvider implements ServiceProviderInterface {
211 | public function register( $container ) {
212 | $container['my_service'] = function( $container ) {
213 | return new MyService( $container['my_dependency'] );
214 | };
215 | }
216 |
217 | public function boot( $container ) {
218 | // bootstrap code if needed
219 | }
220 | }
221 | ```
222 |
223 | - Register dependencies into the service container and boot them, if needed.
224 | - Enables to split your dependencies logically into separate providers.
225 | - WP Emerge's own dependencies are setup via Service providers.
226 |
227 | ---
228 |
229 | #### PHP View Layouts
230 |
231 | `index.php`
232 | ```php
233 | ', '' );
251 | }
252 |
253 | \App::layoutContent();
254 |
255 | \App::render( 'sidebar' );
256 |
257 | \App::render( 'footer' );
258 | ```
259 |
260 | - Eliminate repeating `get_header()`/`get_footer()` calls in every view.
261 | - Reduce boilerplate and improve maintainability of views without sacrificing flexibility.
262 |
263 | ---
264 |
265 | #### Custom view engine support
266 |
267 | ```php
268 | // Run this inside the register() method of a service provider.
269 | $container[ WPEMERGE_VIEW_ENGINE_KEY ] = function( $container ) {
270 | return new MyViewEngine();
271 | };
272 | ```
273 |
274 | - Replace the view engine used in the service container.
275 | - Blade and Twig available as add-on packages.
276 | - You can even write your own view engine and use it seamlessly.
277 |
278 | ## Contributing
279 |
280 | WP Emerge is completely open source and we encourage everybody to participate by:
281 |
282 | - Reviewing `.github/CONTRIBUTING.md`.
283 | - ⭐ the project on GitHub \([https://github.com/htmlburger/wpemerge](https://github.com/htmlburger/wpemerge)\)
284 | - Posting bug reports \([https://github.com/htmlburger/wpemerge/issues](https://github.com/htmlburger/wpemerge/issues)\)
285 | - (Emailing security issues to [hi@atanas.dev](mailto:hi@atanas.dev) instead)
286 | - Posting feature suggestions \([https://github.com/htmlburger/wpemerge/issues](https://github.com/htmlburger/wpemerge/issues)\)
287 | - Posting and/or answering questions \([https://github.com/htmlburger/wpemerge/issues](https://github.com/htmlburger/wpemerge/issues)\)
288 | - Submitting pull requests \([https://github.com/htmlburger/wpemerge/pulls](https://github.com/htmlburger/wpemerge/pulls)\)
289 | - Sharing your excitement about WP Emerge with your community
290 |
--------------------------------------------------------------------------------
/framework/quickstart.md:
--------------------------------------------------------------------------------
1 | # Quickstart
2 |
3 | 1. Run the following in your theme directory:
4 | ```bash
5 | composer require htmlburger/wpemerge
6 | ```
7 | 2. Create a new file for your main Application class, a useful convention is to use `app/src/App.php`:
8 | ```php
9 | get()->url( '/' )->handle( function() {
26 | return 'Hello World!';
27 | } );
28 | ```
29 | 4. Add the following to the **beginning** of your `functions.php`:
30 | ```php
31 | // Load our composer dependencies.
32 | require_once 'vendor/autoload.php';
33 |
34 | // Load our App class.
35 | require_once 'app/src/App.php';
36 |
37 | // Bootstrap our Application.
38 | \App::make()->bootstrap( [
39 | 'routes' => [
40 | 'web' => [
41 | 'definitions' => __DIR__ . '/app/routes/web.php',
42 | ],
43 | ],
44 | ] );
45 | ```
46 | 5. If you open your website's homepage in your browser you will now be greeted with `Hello World!`.
47 |
48 | ## Optional: Setting up autoloading for your own classes
49 |
50 | 1. Add the following to your `composer.json`:
51 | ```js
52 | "autoload": {
53 | "psr-4": {
54 | "App\\": "app/"
55 | }
56 | }
57 | ```
58 | - `App` represents the base namespace for your classes
59 | - `app/` represents the base path for your classes relative to your theme (i.e. `twentyseventeen/app`)
60 |
61 | With this change any class in the `App\` namespace will be autoloaded from the `app/` directory relative to your `composer.json`.
62 | 2. Run `composer dump-autoload` so your changes take effect
63 |
64 | Here are a few example classes (and their filepaths) that will be autoloaded:
65 |
66 | | Class | File |
67 | |----------------------------- |---------------------------------- |
68 | | `App\MyClass` | `app/MyClass.php` |
69 | | `App\Controllers\Web\Home` | `app/Controllers/Web/Home.php` |
70 | | `App\ViewComposers\UserBadge` | `app/ViewComposers/UserBadge.php` |
71 |
72 | You can find more information about PSR-4 autoloading at http://www.php-fig.org/psr/psr-4/
73 |
--------------------------------------------------------------------------------
/framework/routing/conditions.md:
--------------------------------------------------------------------------------
1 | # Route Conditions
2 |
3 | ## Post ID
4 |
5 | Match the detail page of a post by its id:
6 |
7 | ```php
8 | \App::route()->get()->where( 'post_id', 10 )->handle( $handler );
9 | ```
10 |
11 | ## Post slug
12 |
13 | Match the detail page of a post by its slug:
14 |
15 | ```php
16 | \App::route()->get()->where( 'post_slug', 'about-us' )->handle( $handler );
17 | ```
18 |
19 | ## Post template
20 |
21 | Match the detail page of a post by its post template:
22 |
23 | ```php
24 | \App::route()->get()->where( 'post_template', 'templates/contact-us.php' )->handle( $handler );
25 | ```
26 |
27 | ## Post status
28 |
29 | Match the detail page of a post by its post status:
30 |
31 | ```php
32 | \App::route()->get()->where( 'post_status', 'publish' )->handle( $handler );
33 | ```
34 |
35 | ## Post type
36 |
37 | Match the detail page of a post by its post type:
38 |
39 | ```php
40 | \App::route()->get()->where( 'post_type', 'product' )->handle( $handler );
41 | ```
42 |
43 | ## Query var
44 |
45 | Match when a specified query var is present (any value is accepted):
46 |
47 | ```php
48 | \App::route()->get()->where( 'query_var', 's' )->handle( $handler );
49 | ```
50 |
51 | This is especially useful when dealing with custom endpoints ([add_rewrite_endpoint()](https://codex.wordpress.org/Rewrite_API/add_rewrite_endpoint)):
52 |
53 | ```php
54 | add_action( 'init', function() {
55 | // remember to refresh your rewrite rules!
56 | add_rewrite_endpoint( 'my_custom_endpoint', EP_PAGES );
57 | } );
58 |
59 | // ...
60 |
61 | \App::route()->get()->where( 'query_var', 'my_custom_endpoint' )->handle( $handler );
62 | ```
63 |
64 | When combined with the post template condition, you can create pages that optionally receive additional parameters in the url using clean url "/sections/" instead of query arguments:
65 |
66 | ```php
67 | add_action( 'init', function() {
68 | // remember to refresh your rewrite rules!
69 | add_rewrite_endpoint( 'secret', EP_PAGES );
70 | } );
71 |
72 | // ...
73 |
74 | \App::route()->get()
75 | ->where( 'post_template', 'templates/page-with-secret.php' )
76 | ->where( 'query_var', 'secret' )
77 | ->handle( $handler );
78 | ```
79 |
80 | You can match with a specific value of the query var as well:
81 |
82 | ```php
83 | \App::route()->get()
84 | ->where( 'query_var', 'some_query_var_name', 'some_query_var_value' )
85 | ->handle( $handler );
86 | ```
87 |
88 | ## URL
89 |
90 | Match against a specific URL path:
91 |
92 | ```php
93 | \App::route()->get()->url( '/foo/bar/' )->handle( $handler );
94 | ```
95 |
96 | ?> Paths in URL conditions are relative to the site's home url.
97 |
98 | !> You should use `query()` on routes which do not match any valid WordPress URL or your WP Query will consider the request as a `404 - Not Found`. You can find more information on this in the dedicated [Query API](https://wpemerge.com/2018/11/15/a-quick-look-into-wp-emerges-new-route-query-api/) blog post.
99 |
100 | ---
101 |
102 | Use parameters in the path:
103 |
104 | ```php
105 | \App::route()->get()
106 | ->url(
107 | '/foo/{param1}/bar/{param2?}/baz/{param3}/{param4?}',
108 | [
109 | 'param3' => '/^\d+$/',
110 | 'param4' => '/^\d+$/',
111 | ]
112 | )
113 | ->handle( function( $request, $view, $param1, $param2, $param3, $param4 ) {
114 | // ...
115 | } );
116 | );
117 | ```
118 |
119 | - `param1` - required, matches everything.
120 | - `param2` - optional, matches everything.
121 | - `param3` - required, matches a custom regular expression.
122 | - `param4` - optional, matches a custom regular expression.
123 |
124 | ?> Parameter values are passed as arguments to the handler method.
125 |
126 | ---
127 |
128 | Filter the WP_Query parameters for your route:
129 |
130 | ```php
131 | \App::route()->get()
132 | ->url( '/foo/bar/{page_id}' )
133 | ->query( function ( $query_vars, $page_id ) {
134 | return [
135 | 'page_id' => intval( $page_id ),
136 | ];
137 | } )
138 | ->handle( $handler );
139 | ```
140 |
141 | ?> Route parameters will be passed as additional arguments to the callable you supply to `->query()`.
142 |
143 | ---
144 |
145 | Match __any__ url:
146 |
147 | ```php
148 | \App::route()->get()->url( '*' )->handle( $handler );
149 | ```
150 |
151 | ?> `\App::route()->all()` uses this internally.
152 |
153 | ## Admin
154 |
155 | Match against a custom WordPress admin page.
156 |
157 | !> WP Emerge will not register any pages when you use this condition - you have to register those pages yourself using [add_menu_page()](https://developer.wordpress.org/reference/functions/add_menu_page/) or [add_submenu_page()](https://developer.wordpress.org/reference/functions/add_submenu_page/), for example: `add_menu_page( 'Page title', 'Top-level menu title', 'manage_options', 'my-menu-page', '__return_false' );`. Note that a callback function must be specified, even if it is `__return_false`, or WordPress won't execute a required hook.
158 |
159 | ```php
160 | \App::route()->get()->where( 'admin', 'my-menu-page' )->handle( $handler );
161 |
162 | \App::route()->get()->where( 'admin', 'my-submenu-page', 'my-menu-page' )->handle( $handler );
163 | ```
164 |
165 | ## AJAX
166 |
167 | Match against an WordPress AJAX request:
168 |
169 | ```php
170 | // Match requests from authenticated users only:
171 | \App::route()->get()->where( 'ajax', 'my-ajax-action', true, false )->handle( $handler );
172 |
173 | // Match requests from unauthenticated users only:
174 | \App::route()->get()->where( 'ajax', 'my-ajax-action', false, true )->handle( $handler );
175 |
176 | // Match requests from any user:
177 | \App::route()->get()->where( 'ajax', 'my-ajax-action', true, true )->handle( $handler );
178 | ```
179 |
180 | ## Custom
181 |
182 | The custom condition allows you to add a callable which must return a boolean (whether the route has matched the current request or not):
183 |
184 | ```php
185 | \App::route()->get()
186 | ->where( function() {
187 | $my_condition = true; // your custom code here
188 | return $my_condition;
189 | } )
190 | ->handle( $handler );
191 | ```
192 |
193 | ---
194 |
195 | You can also pass parameters to use built-in callables:
196 |
197 | ```php
198 | \App::route()->get()
199 | ->where( 'is_tax', 'app_custom_taxonomy' )
200 | ->handle( $handler );
201 | ```
202 |
203 | This makes it possible to use the full range of WordPress conditionals like `is_front_page()`, `is_home()`, `is_post_type_archive()`, `is_tax()`, `is_date()`, `is_author()`, `is_404()` etc.
204 | Any parameters you pass will be provided to both the callable AND the `$handler`:
205 |
206 | ```php
207 | \App::route()->get()
208 | ->where( 'is_tax', 'app_custom_taxonomy' )
209 | ->handle( function( $request, $view, $taxonomy ) {
210 | // $taxonomy is passed after $request and $view which are always passed to handlers.
211 | } );
212 | ```
213 |
214 | This works with anonymous functions as well, which can be used to reduce duplication:
215 |
216 | ```php
217 | \App::route()->get()
218 | ->where(
219 | function( $foo, $bar ) {
220 | // $foo === 'lorem'
221 | // $bar === 'ipsum'
222 | return true;
223 | },
224 | 'lorem',
225 | 'ipsum'
226 | )
227 | ->handle(
228 | function( $request, $view, $foo, $bar ) {
229 | // $foo and $bar are available here as well.
230 | }
231 | );
232 | ```
233 |
234 | !> This use-case is a bit hard to read - exact same usage is not advisable.
235 |
236 | ## Multiple
237 |
238 | To match multiple conditions specify them one after the other:
239 |
240 | ```php
241 | \App::route()->get()
242 | ->where( 'is_tax', 'app_custom_taxonomy' )
243 | ->where( function() {
244 | return true;
245 | } )
246 | ->handle( $handler );
247 | ```
248 |
249 | Multiple conditions will also pass ALL arguments to the handler following the definition order.
250 |
251 | ## Negate
252 |
253 | The negate condition allows you to negate another condition's result. The following example will match any request as long as it is not for the singular view of the post with id of 3:
254 |
255 | ```php
256 | \App::route()->get()->where( '!post_id', 3 )->handle( $handler ); // notice the exclamation mark.
257 | ```
258 |
259 | ?> The negate condition will also pass whatever arguments its child condition passes to the handler.
260 |
261 | ---
262 |
263 | Since not all conditions are defined using strings, here's the full syntax which you can use for any condition:
264 |
265 | ```php
266 | // Negate a single condition:
267 | \App::route()->get()
268 | ->where( 'negate', 'post_id', 3 )
269 | ->handle( $handler );
270 |
271 | // Negate a custom condition:
272 | \App::route()->get()
273 | ->where( 'negate', function() {
274 | return false;
275 | } )
276 | ->handle( $handler );
277 |
278 | // Negate multiple conditions:
279 | \App::route()->get()
280 | ->where( 'negate', [
281 | ['is_tax', 'app_custom_taxonomy'],
282 | [function() {
283 | return true;
284 | }],
285 | ] )
286 | ->handle( $handler );
287 | ```
288 |
289 | ## Extending Conditions
290 |
291 | You can define your own custom condition classes that you can reuse throughout your project. For more information on how to do this please refer to the [Extending](/framework/extending/overview) section.
292 |
--------------------------------------------------------------------------------
/framework/routing/controllers.md:
--------------------------------------------------------------------------------
1 | # Controllers
2 |
3 | A controller can be any class and any method of that class can be used as a route handler.
4 |
5 | ## Requirements
6 |
7 | Route handlers have a couple of requirements:
8 |
9 | 1. Must receive at least 2 arguments
10 | 1. `$request` - an object representing the current request to the server
11 | 2. `$view` - the view filepath WordPress is currently attempting to load
12 | 3. You may have additional arguments depending on the route condition(s) you are using (e.g. URL parameters, custom condition arguments etc.)
13 | 2. Must return one the following:
14 | 1. Any `string` which will be output literally
15 | 2. Any `array` which will be output as a JSON response
16 | 3. an object implementing the `Psr\Http\Message\ResponseInterface` interface.
17 | 3. Can optionally throw exceptions. Make sure you catch these exceptions in your `ErrorHandler` and translate them to responses so that visitors are not greeted with blank pages or stack traces. An example exception that is handled for you by default is the `\WPEmerge\Routing\NotFoundException` exception which is translated to a 404 response.
18 |
19 | ## Instantiation
20 |
21 | By default, WP Emerge will instantiate your controller class and call the specified method.
22 | However, if your controller class is registered in the service container with its class name as the key, then the class will be resolved from the service container instead of being directly instantiated:
23 |
24 | ```php
25 | // Run this inside the register() method of a service provider.
26 | $container[ HomeController::class ] = function( $container ) {
27 | // your custom instantiation code here, e.g.:
28 | return new HomeController();
29 | }
30 | ```
31 |
32 | ## Response Objects
33 |
34 | To return a suitable response object you can use one of the built-in utility functions:
35 |
36 | ```php
37 | class MyController {
38 | public function someHandlerMethod( $request, $view ) {
39 | return \App::view( 'templates/about-us.php' );
40 | return \App::redirect()->to( home_url( '/' ) );
41 | return \App::error( 404 );
42 | return \App::output( 'Hello World!' ); // same as returning a string
43 | return \App::json( ['foo' => 'bar'] ); // same as returning an array
44 | return \App::response(); // a blank response object
45 | }
46 | }
47 | ```
48 |
49 | Since all of the above functions return an object implementing the `ResponseInterface` interface, you can use immutable chain calls to customize the response, e.g. changing the status:
50 |
51 | ```php
52 | class MyController {
53 | public function someHandlerMethod( $request, $view ) {
54 | return \App::view( 'templates/about-us.php' )->withStatus( 201 );
55 | }
56 | }
57 | ```
58 |
59 | ### `\App::output( $output );`
60 |
61 | Returns a new response object with the supplied string as the body.
62 |
63 | ### `\App::view( $views );`
64 |
65 | By default, uses `locate_template( $views )` to resolve a view and applies the view output as the response body.
66 |
67 | Optionally, you can pass context values to be used from inside the view by chaining `->with( ['foo' => 'bar'] )`.
68 |
69 | ### `\App::json( $data );`
70 |
71 | Returns a new response object json encoding the passed data as the body.
72 |
73 | ### `\App::redirect()->to( $url, $status = 302 );`
74 |
75 | Returns a new response object with location and status headers to redirect the user.
76 |
77 | ### `\App::redirect()->back( $fallback, $status = 302 );`
78 |
79 | Returns a new response object with location and status headers to redirect the user. By default it will use the `Referer` request header. If one is not specified, it will use the supplied `$fallback` as the url. If neither is specified it will use the current request url instead.
80 |
81 | ### `\App::error( $status );`
82 |
83 | Returns a new response object with the supplied status code. Additionally, attempts to render a suitable `{$status}.php` view file.
84 |
85 | ### `\App::response();`
86 |
87 | Returns a blank response object.
88 |
--------------------------------------------------------------------------------
/framework/routing/defining-routes.md:
--------------------------------------------------------------------------------
1 | # Defining Routes
2 |
3 | There are 3 different groups of routes in WP Emerge - `web`, `admin` and `ajax`.
4 | - `web` - Loaded for front-end requests.
5 | - `admin` - Loaded for `/wp-admin/` requests, except `/wp-admin/admin-ajax.php`.
6 | - `ajax` - Loaded for `/wp-admin/admin-ajax.php` requests.
7 |
8 | !> You should almost always avoid using `\App::route()->all()` when defining `admin` or `ajax` routes otherwise you will take over all custom admin pages and/or AJAX requests (even ones created by third party plugins).
9 |
10 | ## Configuration
11 |
12 | To define your desired routes you should create a separate file for each group you intend to use, adding the absolute file path to the configuration:
13 | ```php
14 | \App::make()->bootstrap( [
15 | 'routes' => [
16 | // Assuming your route files are created in /wp-content/themes/my-theme/routes/
17 | 'web' => [
18 | 'definitions' => get_template_directory() . '/routes/web.php',
19 | ],
20 | 'admin' => [
21 | 'definitions' => get_template_directory() . '/routes/admin.php',
22 | ],
23 | 'ajax' => [
24 | 'definitions' => get_template_directory() . '/routes/ajax.php',
25 | ],
26 | ],
27 | // ... other options go here
28 | ] );
29 | ```
30 |
31 | ?> Route files are optional so if you will not be using any `admin` routes you can omit the file from the configuration and skip creating it entirely.
32 |
33 | Routes defined in this way will automatically have the middleware group of the same name applied to them so if you wish to have some custom middleware applied to all of your `web` routes, for example, you can add them to the `web` middleware group in the `middleware_groups` configuration option. You can read more on the subject in the [Configuration](/framework/configuration) and [Middleware](/framework/routing/middleware) articles.
34 |
35 | ## Route Definition
36 |
37 | A typical route definition consists of several attribute declarations and a finalizer, for example:
38 | ```php
39 | \App::route()->get()->url( '/' )->handle( 'HomeController@index' );
40 | ```
41 | Let's break it down:
42 | - `\App::route()` - The route() utility allows us to start registering a new route. All of your routes will start this way.
43 | - `get()` - Shorthand for `methods( ['GET'] )`. See below for more information on the `methods` attribute.
44 | - `url( '/' )` - Shorthand for `where( 'url', '/' )`. See below for more information on `where` attribute.
45 | - `handle( 'HomeController@index' )` - Finalize the definition as a single route which is handled by `HomeController@index` when its conditions are satisfied.
46 |
47 | !> Not finalizing a route with `view()`, `handler()` or `group()` will invalidate the route.
48 |
49 | !> Setting the same attribute multiple times will merge it. Take a look at every attribute below to see how merging happens.
50 |
51 | ## Finalizing Definition
52 |
53 | To finalize a definition you have to call one of the following methods:
54 | - `\App::route()->...->handle( $handler )` - Finalize as a single route with the specified handler when the route condition is satisfied.
55 | - `\App::route()->...->view( $view )` - Shortcut to finalizing a single route with a handler that only renders the specified view.
56 | - `\App::route()->...->group( $routes )` - Finalize as a route group.
57 |
58 | ## Route Groups
59 |
60 | Route groups represent a collection of attributes that should be applied to all routes and child groups within that group.
61 | To create a group finalize a route definition with `group()` instead of `handle()` like this:
62 | ```php
63 | \App::route()->url( '/dashboard/' )->group( function () {
64 | // Group routes go here, for example:
65 | \App::route()->get()->url( '/profile/' )->handle( 'DashboardController@profile' );
66 | \App::route()->get()->url( '/orders/' )->handle( 'DashboardController@orders' );
67 | // ...
68 | } );
69 | ```
70 |
71 | In the above example we define 2 routes matching GET requests for `/dashboard/profile/` and `/dashboard/orders/`. As you can see, the URL we defined for the group gets merged with the URL for each individual route.
72 |
73 | ?> Instead of an anonymous function you can also pass an absolute path to a file which contains your route definitions for that group.
74 |
75 | ## Attributes
76 |
77 | ### Methods
78 |
79 | The `methods` attribute defines which request methods a route should match:
80 | ```php
81 | \App::route()->methods( ['GET', 'POST'] )->...
82 | ```
83 |
84 | There are also shorthand methods for every request method type (and even any request method):
85 | ```php
86 | \App::route()->get()->...
87 | \App::route()->post()->...
88 | \App::route()->put()->...
89 | \App::route()->patch()->...
90 | \App::route()->delete()->...
91 | \App::route()->options()->...
92 | \App::route()->any()->...
93 | ```
94 |
95 | #### Merging Methods
96 |
97 | When 2 `methods` attributes are merged, their values get added together:
98 | ```php
99 | \App::route()->get()->post()->...
100 | // is equal to:
101 | \App::route()->methods( ['GET', 'POST'] )->...
102 | ```
103 |
104 | ### Where
105 |
106 | The `where` attribute defines the condition(s) under which the route should be satisfied. For example, if we wish to have a route that matches when a user visits the `/dashboard/` URL we can use the built-in `url` condition:
107 | ```php
108 | \App::route()->where( 'url', '/dashboard/' )->...
109 | ```
110 | There's also a shorthand available:
111 | ```php
112 | \App::route()->url( '/dashboard/' )->...
113 | // is equal to:
114 | \App::route()->where( 'url', '/dashboard/' )->...
115 | ```
116 |
117 | You can find a full list of built-in conditions in the [Conditions](/framework/routing/conditions) article.
118 |
119 | #### Merging Where
120 |
121 | When 2 `where` attributes are merged, their values get added together into a `multiple` condition which requires all of its conditions to be satisfied. The only exception is the `url` condition which gets concatenated with other `url` conditions.
122 | ```php
123 | \App::route()->url( '/dashboard/' )->url( '/profile/' )...
124 | // is equal to:
125 | \App::route()->where( 'url', '/dashboard/profile/' )->...
126 |
127 | \App::route()->where( 'post_type', 'page' )->where( 'post_slug', 'dashboard' )...
128 | // is equal to:
129 | \App::route()->where( [
130 | ['post_type', 'page'],
131 | ['post_slug', 'dashboard'],
132 | ] )->...
133 | ```
134 |
135 | ### Middleware
136 |
137 | The `middleware` attributes defines the middleware that should be applied to the route:
138 | ```php
139 | \App::route()->middleware( 'auth' )->...
140 | \App::route()->middleware( ['auth', 'cache'] )->...
141 | ```
142 |
143 | #### Merging Middleware
144 |
145 | When 2 `middleware` attributes are merged, their values get added together:
146 | ```php
147 | \App::route()->middleware( 'auth' )->middleware( 'cache' )->...
148 | // is equal to:
149 | \App::route()->middleware( ['auth', 'cache'] )->...
150 | ```
151 |
152 | ### Query
153 |
154 | The `query` attribute defines a filter that should be applied to the query vars passed to the main `WP_Query` instance when making front-end requests:
155 | ```php
156 | \App::route()->query( function ( $query_vars ) {
157 | return array_merge( $query_vars, [
158 | // For example, change the number of posts for the current request to 20:
159 | 'posts_per_page' => 20,
160 | ] );
161 | } )->...
162 | ```
163 |
164 | !> By default, only routes using the `url` condition can have this attribute applied as all other built-in conditions rely on the main query.
165 |
166 | #### Merging Query
167 |
168 | When 2 `query` attributes are merged, their filters will be executed in the order that they are defined (the latter receiving the filtered value from the former):
169 | ```php
170 | \App::route()->query( $filter1 )->query( $filter2 )->...
171 | // is equal to:
172 | \App::route()->query( function ( $query_vars ) {
173 | $query_vars = $filter1( $query_vars );
174 | $query_vars = $filter2( $query_vars );
175 | return $query_vars;
176 | } )->...
177 | ```
178 |
179 | ### Namespace
180 |
181 | The `namespace` attribute defines what namespace should be automatically prepended to the route handler:
182 | ```php
183 | \App::route()->setNamespace( '\\App\\Controllers\\Web\\Dashboard\\' )->...
184 | ```
185 |
186 | ?> The `namespace` attribute is set using `setNamespace` as PHP<7 does not allow method names to match reserved keywords.
187 |
188 | This is especially useful if you have namespaces for different route groups, for example:
189 | ```php
190 | \App::route()->url( '/dashboard/' )
191 | ->setNamespace( '\\App\\Controllers\\Web\\Dashboard\\' )
192 | ->group( function () {
193 | // Match /dashboard/profile/ ...
194 | \App::route()->get( '/profile/' )->handle( 'Profile@index' );
195 | // ... using \App\Controllers\Web\Dashboard\Profile@index as the handler.
196 | } );
197 | ```
198 |
199 | #### Merging Namespace
200 |
201 | When 2 `namespace` attributes are merged, the latter will override the former:
202 | ```php
203 | \App::route()->setNamespace( '\\App\\First\\' )->setNamespace( '\\App\\Second\\' )->...
204 | // is equal to:
205 | \App::route()->setNamespace( '\\App\\Second\\' )->...
206 | ```
207 |
208 | ### Name
209 |
210 | The `name` attribute defines an arbitrary unique name for the route:
211 | ```php
212 | \App::route()->name( 'dashboard' )->...
213 | ```
214 | This name can then be used to generate a URL for the route in your views:
215 | ```php
216 | Dashboard
217 | ```
218 |
219 | ?> By default, `routeUrl()` can only be used for routes with one of the following conditions: `url`, `post_id`, `ajax`, `admin`.
220 |
221 | If the route condition has parameters, you can pass them as an array to `routeUrl()`:
222 | ```php
223 | // Route:
224 | \App::route()->get()->url( '/dashboard/{username}' )->name('dashboard')->...
225 | // Link:
226 | Dashboard
227 | ```
228 |
229 | #### Merging Name
230 |
231 | When 2 `name` attributes are merged in a route, the latter will override the former:
232 | ```php
233 | \App::route()->name( 'first' )->name( 'second' )->...
234 | // is equal to:
235 | \App::route()->name( 'second' )->...
236 | ```
237 | __However__, when a group name is merged into a route name they will be concatenated with a dot character:
238 | ```php
239 | \App::route()
240 | ->url( '/dashboard' )
241 | ->name( 'dashboard' )
242 | ->group( function () {
243 | \App::route()->get()->url( '/' )->name('home')->handle( 'DashboardController@home' );
244 | // -> will result in a route name of 'dashboard.home'
245 |
246 | \App::route()->get()->url( '/settings' )->name('settings')->handle( 'DashboardController@settings' );
247 | // -> will result in a route name of 'dashboard.settings'
248 | } );
249 | ```
250 |
--------------------------------------------------------------------------------
/framework/routing/error-handling.md:
--------------------------------------------------------------------------------
1 | # Error Handling
2 |
3 | WP Emerge comes with a basic `ErrorHandler` class which is used to translate errors and exceptions to response objects. It is often a good idea to extend or replace that class in order to customize error handling.
4 |
5 | ## Development
6 |
7 | In development mode, the [filp/whoops](https://github.com/filp/whoops) package is included which provides you with a beautiful and interactive stack trace interface whenever an error occurs:
8 | 
9 |
10 | ## Production
11 |
12 | In production, any unhandled errors or exceptions will be translated to a 500 error and the first available view will be loaded following this view hierarchy:
13 |
14 | 1. `{$status}.php`
15 | 2. `error.php`
16 | 3. `index.php`
17 |
18 | ## Customization
19 |
20 | A popular use case for custom error handling is to translate common exceptions to responses - this way you will have handy shortcuts in controller methods. For example, you can throw a custom `ValidationException` and then translate it to a redirect response with flashed error messages to handle invalid form requests.
21 |
22 | The default `ErrorHandler` class comes with automatic handling for the built-in `\WPEmerge\Routing\NotFoundException` exception. When thrown it will be translated to a 404 response by setting the status header to 404 and using the `404.php` view:
23 |
24 | ```php
25 | use WPEmerge\Routing\NotFoundException;
26 |
27 | // ...
28 |
29 | public function index( $request, $view ) {
30 | // ...
31 | if ( ! $some_entity ) {
32 | throw new NotFoundException();
33 | }
34 | // ...
35 | }
36 | ```
37 |
38 | To use a custom `ErrorHandler` class, replace the `WPEMERGE_EXCEPTIONS_ERROR_HANDLER_KEY` key in the service container with a class that implements the `\WPEmerge\Exceptions\ErrorHandlerInterface` interface:
39 |
40 | ```php
41 | // Run this inside the register() method of a service provider.
42 | $container[ WPEMERGE_EXCEPTIONS_ERROR_HANDLER_KEY ] = function() {
43 | return new MyCustomErrorHandler();
44 | };
45 | ```
46 |
--------------------------------------------------------------------------------
/framework/routing/groups.md:
--------------------------------------------------------------------------------
1 | # Route Groups
2 |
3 | You can group routes which share attributes:
4 |
5 | ```php
6 | \App::route()
7 | ->middleware( 'mymiddleware' )
8 | ->url( '/foo/' )
9 | ->group( function() {
10 | \App::route()
11 | ->url( '/bar/' )
12 | ->group( function() {
13 | // Match if '/foo/bar/' is the full path:
14 | \App::route()->get()->url( '/' )->handle( $handler );
15 |
16 | // Match if '/foo/bar/baz/' is the full path:
17 | \App::route()->get()->url( '/baz/' )->handle( $handler );
18 | } );
19 |
20 | // Match if '/foo/' is the full path
21 | // AND the query var 'my_query_var' is present:
22 | \App::route()->get()->where( 'query_var', 'my_query_var' )->handle( $handler );
23 | } );
24 | ```
25 |
26 | !> URL conditions will be concatenated as long as they are in a chain which starts from a root group. The
27 | following examples will **NOT** concatenate URL conditions:
28 |
29 | ```php
30 | // Root condition is not a URL:
31 | \App::route()
32 | ->where( 'post_id', 1 )
33 | ->group( function() {
34 | // Match if the current query loads the single post with id of 1
35 | // AND '/foo/' is the full path
36 | // -> this usage is fine so far
37 | \App::route()
38 | ->url( '/foo/' )
39 | ->group( function() {
40 | // Match if the current query loads the single post with id of 1
41 | // AND '/foo/' is the full path
42 | // AND '/bar/' is the full path
43 | // -> The above will always fail since both '/foo/' and '/bar/' are required
44 | // -> to be the full path as we've started with a non-URL root condition
45 | \App::route()->get()->url( '/bar/' )->handle( $handler );
46 | } );
47 | } );
48 |
49 | // Root condition is a URL:
50 | \App::route()
51 | ->url( '/foo/' )
52 | ->group( function() {
53 | // Match if '/foo/' is the full path
54 | // AND the current query loads the single post with id of 1
55 | // -> this usage is fine, but note that we are breaking the URL chain
56 | \App::route()
57 | ->where( 'post_id', 1 )
58 | ->group( function() {
59 | // Match if '/foo/' is the full path
60 | // AND the current query loads the single post with id of 1
61 | // AND '/bar/' is the full path
62 | // -> the above will always fail since both '/foo/' and '/bar/' are required
63 | // -> to be the full path as we've broken the URL condition chain
64 | \App::route()->get()->url( '/bar/' )->handle( $handler );
65 | } );
66 | } );
67 | ```
68 |
--------------------------------------------------------------------------------
/framework/routing/handlers.md:
--------------------------------------------------------------------------------
1 | # Route Handlers
2 |
3 | A route handler can be one of the following:
4 | - An anonymous function.
5 | - A reference in the `[ ClassName::class, 'METHOD_NAME' ]` format.
6 | - A reference in the `'CLASS_NAME@METHOD_NAME'` format.
7 |
8 | ?> If the specified class name does not exist, by default, `\App\Controllers\Web\` is automatically prepended for convenience.
9 |
10 | The following example will create a new instance of the `\App\Controllers\Web\HomeController` class and call its `index` method:
11 |
12 | ```php
13 | \App::route()->get()->url( '/' )->handle( [ HomeController::class, 'index' ] );
14 | // or ...
15 | \App::route()->get()->url( '/' )->handle( 'HomeController@index' );
16 | ```
17 |
18 | Refer to the [Controllers](/framework/routing/controllers) section for more information on route handlers.
19 |
--------------------------------------------------------------------------------
/framework/routing/methods.md:
--------------------------------------------------------------------------------
1 | # Route Methods
2 |
3 | The method you call when you create a route defines which request method the route will match:
4 |
5 | ```php
6 | \App::route()->[get|post|put|patch|delete|options|any]();
7 | ```
8 |
9 | If you wish to match a specific set of methods you can also use the generic `\App::route()->methods()` method:
10 |
11 | ```php
12 | \App::route()->methods( ['GET', 'HEAD', 'POST'] );
13 | ```
14 |
15 | ## Handling all requests
16 |
17 | By default, WP Emerge will only handle the requests which match its routes so you can implement it only where you need to (even on legacy projects). However, you can also handle all requests if you wish to do so:
18 | ```php
19 | // Add this AFTER all of your route definitions
20 | \App::route()->all();
21 | ```
22 |
23 | Adding this will initially seem like it makes no difference because WP Emerge will make sure requests produce the same results as normal WordPress requests would, however, there are a couple notable differences:
24 |
25 | 1. Global middleware will be applied to ALL requests (since this declaration will match all requests)
26 | 2. All views will be rendered using WP Emerge's current view engine. By default there will be no difference, however, if you use a different view engine all WordPress templates will be rendered through it.
27 |
28 | _Check out [NameProxy](/framework/views/overview#nameproxyviewengine) if you wish to have mixed views._
29 |
--------------------------------------------------------------------------------
/framework/routing/middleware.md:
--------------------------------------------------------------------------------
1 | # Middleware
2 |
3 | ## Route Middleware
4 |
5 | Middleware allow you to modify the request and/or response before and/or after it reaches the route handler. Middleware can be any of the following:
6 | 1. the class name of a class that has a method with the following signature:
7 | `public function handle( \WPEmerge\Requests\RequestInterface $request, \Closure $next )`
8 | 2. an alias of a middleware class as defined in the `middleware` key of your configuration. **This is the recommended way of using middleware.**
9 |
10 | A common example for middleware usage is protecting certain routes to be accessible by logged in users only:
11 |
12 | ```php
13 | class AuthenticationMiddleware {
14 | public function handle( $request, $next ) {
15 | if ( ! is_user_logged_in() ) {
16 | $return_url = $request->getUrl();
17 | $login_url = wp_login_url( $return_url );
18 | return \App::redirect()->to( $login_url );
19 | }
20 | return $next( $request );
21 | }
22 | }
23 |
24 | \App::route()->get()
25 | ->url( '/protected-url/')
26 | ->middleware( AuthenticationMiddleware::class )
27 | ->handle( ... );
28 | ```
29 |
30 | ?> There's built-in middleware that deals with this exact use case - `user.logged_in`. Check out the [Built-in Middleware](#built-in-middleware) section below for more information.
31 |
32 | You can also define middleware that is automatically applied to all routes - check out the [Configuration](/framework/configuration) page for more details.
33 |
34 | !> Middleware is only applied on defined routes - normal WordPress requests that do not match any route will NOT have middleware applied. To apply middleware to all requests you have to match all requests with routes. Take a look at [Handling all requests](/framework/routing/methods#handling-all-requests) for an easy way to achieve this.
35 |
36 | ## Controller Middleware
37 |
38 | Another way you can specify middleware is by declaring it in your controller's `__construct()` method. To do so, follow these steps:
39 | 1. Implement the `HasControllerMiddlewareInterface` interface and use the `HasControllerMiddlewareTrait` trait like so:
40 | ```php
41 | use WPEmerge\Middleware\HasControllerMiddlewareInterface;
42 | use WPEmerge\Middleware\HasControllerMiddlewareTrait;
43 |
44 | class MyController implements HasControllerMiddlewareInterface {
45 | use HasControllerMiddlewareTrait;
46 |
47 | // ...
48 | }
49 | ```
50 | 2. Declare the `__construct()` method if you haven't already:
51 | ```php
52 | public function __construct() {
53 |
54 | }
55 | ```
56 | 3. Add your middleware using the `middleware()` method:
57 | ```php
58 | public function __construct() {
59 | $this->middleware( 'mymiddleware' );
60 | }
61 | ```
62 |
63 | Here's a full example:
64 | ```php
65 | class UserDashboard implements HasControllerMiddlewareInterface {
66 | use HasControllerMiddlewareTrait;
67 |
68 | public function __construct() {
69 | // Apply the 'csrf' middleware to all methods of this controller:
70 | $this->middleware( 'csrf' );
71 |
72 | // Apply the 'user.logged_in' middleware to all methods of this
73 | // controller except 'login':
74 | $this->middleware( 'user.logged_in' )->except( 'login' );
75 |
76 | // Apply the 'user.logged_out' middleware only to the 'login' method
77 | // of this controller:
78 | $this->middleware( 'user.logged_out' )->only( 'login' );
79 | }
80 |
81 | public function login() {
82 | // ...
83 | }
84 |
85 | public function logout() {
86 | // ...
87 | }
88 | }
89 | ```
90 |
91 | ## Passing arguments to middleware
92 |
93 | Another benefit of using middleware aliases is that they enable you to pass arguments to middleware in a comma-separated list.
94 |
95 | For example, if you have a middleware class that limits access based on the capabilities of the current user you can reuse it for different capabilities by passing an argument:
96 |
97 | Our middleware class:
98 | ```php
99 | class CapabilityMiddleware {
100 | // Note the new $capability parameter:
101 | public function handle( RequestInterface $request, Closure $next, $capability ) {
102 | if ( ! current_user_can( $capability ) ) {
103 | // Return a 404 when the current user fails the capability check:
104 | throw new NotFoundException();
105 | }
106 |
107 | return $next( $request );
108 | }
109 | }
110 | ```
111 |
112 | Defining the middleware alias:
113 | ```php
114 | \App::make()->bootstrap( [
115 | 'middleware' => [
116 | 'capability' => CapabilityMiddleware::class,
117 | ],
118 | // ...
119 | ] );
120 | ```
121 |
122 | Passing `manage_options` as the required capability to the middleware:
123 | ```php
124 | \App::route()->middleware( 'capability:manage_options' )->...
125 | ```
126 |
127 | ?> There's built-in middleware that deals with this exact use case - `user.can`. Check out the [Built-in Middleware](#built-in-middleware) section below for more information.
128 |
129 | ## Middleware Groups
130 |
131 | Commonly used middleware can be grouped up so you do not have to list it every time and pass the same arguments (if any). To define a new middleware group you have to add a new key to the `middleware_groups` configuration option with a value of the array of middleware that you wish this group to include:
132 | ```php
133 | \App::make()->bootstrap( [
134 | 'middleware_groups' => [
135 | 'mygroup' => [
136 | 'mymiddleware1',
137 | 'mymiddleware2',
138 | // ...
139 | ],
140 | ],
141 | ] );
142 | ```
143 |
144 | Using middleware groups is done in exactly the same way as you would use a single middleware alias:
145 | ```php
146 | \App::route()->middleware( 'mygroup' )->...
147 | ```
148 |
149 | Refer to the [Configuration](/framework/configuration) article for more information on middleware groups.
150 |
151 | ## Order of Execution
152 |
153 | Middleware is sorted by priority as specified in the `'middleware_priority'` key of your [configuration](/framework/configuration).
154 |
155 | !> When compared, middleware that is not specified in the priority array will be executed after all middleware that is and will keep its relative order to other middleware without a specified priority.
156 |
157 | ## Built-in Middleware
158 |
159 | ### flash
160 |
161 | Flash middleware is applied globally by default. Check out the [Flash](/framework/tools/flash) article for more information.
162 |
163 | ### old_input
164 |
165 | OldInput middleware is applied globally by default. Check out the [OldInput](/framework/tools/oldinput) article for more information.
166 |
167 | ### csrf
168 |
169 | CSRF middleware is **NOT** applied globally by default. Check out the [CSRF Protection](/framework/tools/csrf-protection) article for more information.
170 |
171 | ### user.logged_in:redirect_url
172 |
173 | Require the current user to be logged in redirecting non-logged in users to the login page:
174 | ```php
175 | \App::route()->middleware( 'user.logged_in' )->...
176 | ```
177 |
178 | Optionally, you can specify a custom url to redirect to:
179 | ```php
180 | \App::route()->middleware( 'user.logged_in:http://example.com' )->...
181 | ```
182 |
183 | You can also filter the final url:
184 | ```php
185 | add_filter( 'wpemerge.middleware.user.logged_in.redirect_url', function ( $url, $request ) {
186 | return 'http://example.com';
187 | }, 10, 2 );
188 | ```
189 |
190 | ### user.logged_out:redirect_url
191 |
192 | The opposite of `user.logged_in` - require the current user to be logged out redirecting logged in users to the home page:
193 | ```php
194 | \App::route()->middleware( 'user.logged_out' )->...
195 | ```
196 |
197 | Optionally, you can specify a custom url to redirect to:
198 | ```php
199 | \App::route()->middleware( 'user.logged_out:http://example.com' )->...
200 | ```
201 |
202 | You can also filter the final url:
203 | ```php
204 | add_filter( 'wpemerge.middleware.user.logged_out.redirect_url', function ( $url, $request ) {
205 | return 'http://example.com';
206 | }, 10, 2 );
207 | ```
208 |
209 | ### user.can:capability,object_id,redirect_url
210 |
211 | Require the current user to have a capability redirecting users who do not to the homepage:
212 | ```php
213 | \App::route()->middleware( 'user.can:edit_posts' )->...
214 | ```
215 |
216 | Optionally, you can specify an object ID for the capability check:
217 | ```php
218 | \App::route()->middleware( 'user.can:edit_post,10' )->...
219 | ```
220 |
221 | Optionally, you can specify a custom url to redirect to:
222 | ```php
223 | \App::route()->middleware( 'user.can:edit_posts,0,http://example.com' )->...
224 | ```
225 |
226 | You can also filter the capability:
227 | ```php
228 | add_filter( 'wpemerge.middleware.user.can.capability', function ( $capability, $request ) {
229 | return 'edit_posts';
230 | }, 10, 2 );
231 | ```
232 |
233 | ... the object ID:
234 | ```php
235 | add_filter( 'wpemerge.middleware.user.can.object_id', function ( $object_id, $capability, $request ) {
236 | return 10;
237 | }, 10, 3 );
238 | ```
239 |
240 | ... and the final url:
241 | ```php
242 | add_filter( 'wpemerge.middleware.user.can.redirect_url', function ( $url, $request ) {
243 | return 'http://example.com';
244 | }, 10, 2 );
245 | ```
246 |
--------------------------------------------------------------------------------
/framework/routing/request-lifecycle.md:
--------------------------------------------------------------------------------
1 | # Request Lifecycle
2 |
3 | In order to enable WP Emerge you first have to boot it. This is usually done in your plugin's main `.php` file or your theme's `functions.php` file as it is early enough to allow WP Emerge to hook itself into required WordPress actions. Once WP Emerge is booted, it will hook into the `template_include` action to process the request. This means that there are 2 major parts to the request lifecycle:
4 |
5 | ## Bootstrapping
6 |
7 | 1. Configuration options passed to `\App::make()->bootstrap( $config )` are loaded.
8 | 2. All service providers listed in the configuration are registered.
9 | 3. All service providers listed in the configuration are booted.
10 |
11 | !> Step 2 and 3 are a critical part of bootstrapping which is why you should make sure your own service container registrations or overrides are done in your own Service Provider instead of after WP Emerge has been booted.
12 |
13 |
14 | ## `template_include` action
15 |
16 | 1. All defined routes are evaluated in the order they are defined until a satisified route is found.
17 | - If no route is satisfied, normal WordPress execution takes place and no further action is taken by WP Emerge.
18 | 2. If a route is satisfied, normal WordPress template output will be halted and WP Emerge will take over.
19 | 3. All suitable arguments depending on the route condition are prepared and passed to the route handler.
20 | 4. All middleware is sorted according to the middleware priority array and is executed. At the end of the middleware chain, the route handler (a controller method, for example) is executed. The middleware and route handler chain will be referred to as the `pipeline`.
21 | 5. If an exception is thrown from the pipeline the `ErrorHandler` defined in the service container will be invoked with that exception as its argument and the pipeline will be halted. The error handler must return a corresponding response object.
22 | 6. The returned response object from the pipeline or the error handler will be used to set the headers and output the body, ending the response.
23 |
24 | ## WP Emerge and The Loop
25 |
26 | Since WP Emerge hooks right before the first template is loaded, the main WordPress query is not interrupted and you can use The Loop as you normally would.
27 |
28 | ## WordPress AJAX
29 |
30 | AJAX routes are handled in the same way but use the appropriate `wp_ajax_*` and `wp_ajax_nopriv_*` hooks instead of `template_include`.
31 |
32 | ## WordPress Admin
33 |
34 | Admin routes are handled in the same way but use the appropriate page `{$admin_page_hook}` and `load-{$admin_page_hook}` hooks instead of `template_include`. In addition, the response is split with the headers being sent during `load-{$admin_page_hook}` while the body of the response is sent during `{$admin_page_hook}`.
35 |
--------------------------------------------------------------------------------
/framework/tools/app-shortcuts.md:
--------------------------------------------------------------------------------
1 | # \App shortcuts
2 |
3 | ## \App::app()
4 |
5 | `\App::app();`
6 |
7 | Get the internal application instance.
8 |
9 | ## \App::resolve()
10 |
11 | `\App::resolve( $key );`
12 |
13 | Resolve a key from the dependency injection container:
14 |
15 | ```php
16 | $service = \App::resolve( 'some_service_key' );
17 | ```
18 |
19 | !> Using a [service provider](/framework/tools/service-providers.md) to inject your dependencies is the better approach - only use this shortcut sparingly.
20 |
21 | ## \App::container()
22 |
23 | `\App::container();`
24 |
25 | Get the application dependency injection container instance:
26 |
27 | ```php
28 | $container = \App::container();
29 | ```
30 |
31 | ## \App::render()
32 |
33 | `\App::render( $views, $context = [] )`
34 |
35 | Render the first view that exists with the given context.
36 |
37 | ```php
38 | // Render a specific view:
39 | \App::render( 'content' );
40 |
41 | // Render the first view that exists:
42 | \App::render( ['views/content-single', 'views/content'] );
43 | ```
44 |
45 | ## \App::route()
46 |
47 | `\App::route()`
48 |
49 | Start a [route definition](/framework/routing/defining-routes.md).
50 |
51 | ```php
52 | \App::route()->get()->where( 'is_home' )->handle( 'HomeController@index' );
53 | ```
54 |
55 | ## \App::router()
56 |
57 | `\App::router()`
58 |
59 | Get the Router service instance.
60 |
61 | ```php
62 | \App::route()->get()->where( 'is_home' )->handle( 'HomeController@index' );
63 | ```
64 |
65 | ## \App::run()
66 |
67 | `\App::run( RequestInterface $request, $middleware, $handler, $arguments = [] )`
68 |
69 | Run a request through the specified middleware and handler (including handler middleware, if any) with the given arguments returning a [PSR-7](https://www.php-fig.org/psr/psr-7/) response object outside of the normal WP Emerge flow:
70 |
71 | ```php
72 | use WPEmerge\Requests\Request;
73 |
74 | $response = \App::run(
75 | new Request( 'GET', 'http://mysite.test/' ),
76 | ['web'],
77 | 'HomeController@index'
78 | );
79 |
80 | // If you wish to output the response as usual you can use this:
81 | \App::responses()->respond( $response );
82 | ```
83 |
84 | ## \App::closure()
85 |
86 | `\App::closure()->value( $key );`
87 |
88 | Make a closure that resolves a value from the container:
89 | ```php
90 | $closure = \App::closure()->value( 'my_service' );
91 | $my_service = $closure();
92 | ```
93 |
94 | `\App::closure()->method( $key, $method )`
95 |
96 | Make a closure that resolves a class instance from the container and calls one of its methods.
97 | Useful if you need to pass a callable to an API without container support such as the REST API:
98 | ```php
99 | register_rest_route( 'myplugin/v1', '/author/(?P' . $error . '
'; 36 | } 37 | ``` 38 | -------------------------------------------------------------------------------- /framework/tools/oldinput.md: -------------------------------------------------------------------------------- 1 | # OldInput 2 | 3 | OldInput is a built-in global middleware which allows you to recall POST request input from the previous request ( this will be familiar if you've used [Laravel's old()](https://laravel.com/docs/5.4/requests#old-input) ). 4 | 5 | Since OldInput internally uses Flash, you have to ensure a session is available for it: 6 | ```php 7 | add_action( 'init', function() { 8 | session_start(); 9 | } ); 10 | ``` 11 | 12 | ## Usage 13 | 14 | A typical use case is to fill in field values after an error has occurred with the user's form submission: 15 | ```php 16 | // inside your form view 17 | 18 | ``` 19 | 20 | To reduce verbosity you can define your own simple `old()` function like this: 21 | 22 | ```php 23 | function old() { 24 | return call_user_func_array( [\App::oldInput(), 'get'], func_get_args() ); 25 | } 26 | ``` 27 | -------------------------------------------------------------------------------- /framework/tools/service-providers.md: -------------------------------------------------------------------------------- 1 | # Service Providers 2 | 3 | A service provider is a class that registers and bootstraps services into the WP Emerge service container. 4 | 5 | WP Emerge itself uses service providers to register and bootstrap most of its functionality, for example: 6 | - `\WPEmerge\Flash\FlashServiceProvider` 7 | - `\WPEmerge\Routing\RoutingServiceProvider` 8 | 9 | The external Twig and Blade view implementations also use service providers to add their respective view engines: 10 | - https://github.com/htmlburger/wpemerge-twig - `\WPEmergeTwig\View\ServiceProvider` 11 | - https://github.com/htmlburger/wpemerge-blade - `\WPEmergeBlade\View\ServiceProvider` 12 | 13 | Here's how to register a service provider with WP Emerge: 14 | ```php 15 | \App::make()->bootstrap( [ 16 | 'providers' => [ 17 | SomeServiceProvider::class, 18 | SomeOtherServiceProvider::class, 19 | // ... 20 | ], 21 | // ... other boot options here 22 | ] ); 23 | ``` 24 | 25 | Take a look at the [Extending](/framework/extending/overview) section for a real-world usage example. 26 | -------------------------------------------------------------------------------- /framework/views/global-context.md: -------------------------------------------------------------------------------- 1 | # Global Context 2 | 3 | You can pass variables to all views and partials by adding them as globals using `\App::views()->addGlobal()` or `\App::views()->addGlobals()`. 4 | 5 | First, we need to create a service provider class: 6 | ```php 7 | addGlobal( 'foo', 'bar' ); 27 | 28 | // Add many variables. 29 | \App::views()->addGlobals( [ 30 | 'name' => get_bloginfo( 'name' ), 31 | 'url' => home_url( '/' ), 32 | ] ); 33 | } 34 | } 35 | ``` 36 | 37 | Second, we need to register that service provider in the configuration: 38 | ```php 39 | \App::make()->bootstrap( [ 40 | 'providers' => [ 41 | // ... 42 | \App\View\ViewGlobalContextServiceProvider::class, 43 | ], 44 | // ... 45 | ] ); 46 | ``` 47 | 48 | Then, we can use the registered globals in any view: 49 | ```php 50 | 51 | 52 | 53 | ``` 54 | -------------------------------------------------------------------------------- /framework/views/layouts.md: -------------------------------------------------------------------------------- 1 | # Layouts 2 | 3 | It is a common pattern in WordPress themes to see `get_header()` and `get_footer()` called in every template. In addition, these calls are often followed or preceded by related markup. 4 | In WP Emerge, all of this repetition can be avoided by utilizing layouts. 5 | 6 | !> The layout functionality described below only applies to the default PHP view engine. Other view 7 | engines such as Blade and Twig have their own layout implementation which should be used instead. 8 | 9 | ## Example 10 | 11 | Here's the main `theme/index.php` view of the WP Emerge Starter Theme: 12 | 13 | ```php 14 | ', '' ); 35 | } 36 | 37 | \App::layoutContent(); 38 | 39 | \App::render( 'sidebar' ); 40 | 41 | \App::render( 'footer' ); 42 | ``` 43 | 44 | Nothing unusual about this file except the call to `\App::layoutContent()` - this is what defines where the actual view content should be rendered. Essentially, any view can be used as a layout as long as it calls `\App::layoutContent()` to include the "child" view content. 45 | Also like any other view, layouts can declare their own `Layout` to achieve layout nesting and you can even use View Composers on layouts to pass context values. 46 | 47 | You no longer need to have the header/footer boilerplate in every view while retaining the flexibility of having different header/footer partials for different templates by declaring your desired layouts when needed. 48 | -------------------------------------------------------------------------------- /framework/views/overview.md: -------------------------------------------------------------------------------- 1 | # Views 2 | 3 | WP Emerge comes with a default view engine built-in - `\WPEmerge\View\PhpViewEngine`. 4 | This view engine uses `extract()` for the view context and then includes the view file. The resulting output is then passed as the rendered view string. 5 | Essentially, this engine loads views in the same way WordPress does, but with a couple extra features: 6 | 7 | 1. Context variable passing. 8 | 2. Ability to specify layouts for views. 9 | 10 | ## External view engines 11 | 12 | ### WP Emerge Blade 13 | 14 | Renders your views using Blade: https://github.com/htmlburger/wpemerge-blade 15 | 16 | ### WP Emerge Twig 17 | 18 | Renders your views using Twig: https://github.com/htmlburger/wpemerge-twig 19 | 20 | ## Other built-in view engines 21 | 22 | ### NameProxyViewEngine 23 | 24 | WP Emerge also comes with a small utility view engine which delegates view rendering to other engines depending on the view name suffix. 25 | The main use-case for it is to allow you to use multiple view engines so you can migrate to a new one on a view-by-view basis instead of forcing you to rewrite all of your views. 26 | 27 | Replacing the default view engine: 28 | ```php 29 | // Run this inside the register() method of a service provider. 30 | $container[ WPEMERGE_VIEW_ENGINE_KEY ] = function( $container ) { 31 | return new \WPEmerge\View\NameProxyViewEngine( 32 | $container[ WPEMERGE_APPLICATION_KEY ], 33 | [ 34 | // Format: view name suffix => service container key for alternative engine. 35 | 36 | // Use Twig for twig.php views. 37 | '.twig.php' => WPEMERGETWIG_VIEW_TWIG_VIEW_ENGINE_KEY, 38 | 39 | // Use Blade for .blade.php views. 40 | '.blade.php' => WPEMERGEBLADE_VIEW_BLADE_VIEW_ENGINE_KEY, 41 | 42 | // Use default PHP engine for .php views. 43 | '.php' => WPEMERGE_VIEW_PHP_VIEW_ENGINE_KEY, 44 | 45 | // Use Blade for all other cases as blade views can be referenced 46 | // in blade.format.as.well without an extension. 47 | ], 48 | WPEMERGEBLADE_VIEW_BLADE_VIEW_ENGINE_KEY 49 | ); 50 | }; 51 | ``` 52 | !> The example above assumes you have included both WP Emerge Twig and WP Emerge Blade composer packages. 53 | `WPEMERGETWIG_VIEW_TWIG_VIEW_ENGINE_KEY` and `WPEMERGEBLADE_VIEW_BLADE_VIEW_ENGINE_KEY` are not provided by default. 54 | 55 | ## Implementing other View Engines 56 | 57 | Implementing your own or a third-party engine is straightforward - there are only a couple requirements: 58 | 59 | 1. Your class must implement the `\WPEmerge\View\ViewEngineInterface` interface 60 | ```php 61 | use \WPEmerge\View\ViewEngineInterface; 62 | 63 | class MyCustomViewEngine implements ViewEngineInterface { 64 | // ... 65 | } 66 | ``` 67 | 68 | 2. You must use a service provider class to register your new view engine: 69 | ```php 70 | use \WPEmerge\ServiceProviders\ServiceProviderInterface; 71 | 72 | class MyCustomServiceProvider implements ServiceProviderInterface { 73 | public function register( $container ) { 74 | $container['my_custom_view_engine'] = function ( $c ) { 75 | return new MyCustomViewEngine(); 76 | }; 77 | } 78 | // ... 79 | } 80 | ``` 81 | 3. ... and to replace the built-in engine: 82 | ```php 83 | use \WPEmerge\ServiceProviders\ServiceProviderInterface; 84 | 85 | class MyCustomServiceProvider implements ServiceProviderInterface { 86 | public function register( $container ) { 87 | $container['my_custom_view_engine'] = function ( $c ) { 88 | return new MyCustomViewEngine(); 89 | }; 90 | 91 | $container[ WPEMERGE_VIEW_ENGINE_KEY ] = function ( $c ) { 92 | return $c['my_custom_view_engine']; 93 | }; 94 | } 95 | // ... 96 | } 97 | ``` 98 | 4. Finally, register your service provider with WP Emerge: 99 | ```php 100 | \App::make()->bootstrap( [ 101 | 'providers' => [ 102 | // ... other providers 103 | MyCustomServiceProvider::class, 104 | ], 105 | // ... other options 106 | ] ); 107 | ``` 108 | -------------------------------------------------------------------------------- /framework/views/view-composers.md: -------------------------------------------------------------------------------- 1 | # View Composers 2 | 3 | View composers prepare context for a view, partial, or layout whenever it is rendered. A view composer can be one of the following: 4 | - An anonymous function. 5 | - A reference in the `[ ClassName::class, 'METHOD_NAME' ]` format. 6 | - A reference in the `'CLASS_NAME@METHOD_NAME'` format. 7 | 8 | !> Default View Engine WARNING: Due to the nature of how `get_template_part()` works, you __MUST__ render partials using `\App::render()` instead of `get_template_part()` in order to support composition. 9 | 10 | !> If you wish to compose core partials (e.g. `header.php`, `footer.php`) that are rendered using a `get_*()` function call (e.g. `get_header()`) you will have to use `\App::render( 'name' )` (e.g. `\App::render( 'header' )`) instead. 11 | 12 | ?> If the specified class name does not exist, by default, `\App\ViewComposers\` is automatically prepended for convenience. 13 | 14 | ?> More information on how to use `\App::render()` is available at the end of this article. 15 | 16 | ## Example 17 | 18 | In this example we want to pass the latest posts to the `templates/partials/latest-news.php` partial. 19 | 20 | First, we need to create a service provider class: 21 | ```php 22 | addComposer( 'templates/partials/latest-news', function( $view ) { 41 | $view->with( [ 42 | 'news' => new WP_Query( [ 43 | 'posts_per_page' => 3, 44 | ] ), 45 | ] ); 46 | } ); 47 | } 48 | } 49 | ``` 50 | 51 | Then, we need to register that service provider in the configuration: 52 | ```php 53 | \App::make()->bootstrap( [ 54 | 'providers' => [ 55 | // ... 56 | \App\ViewComposers\ViewComposersServiceProvider::class, 57 | ], 58 | // ... 59 | ] ); 60 | ``` 61 | 62 | With this, whenever the `latest-news.php` partial is loaded, we will have the `$news` variable automatically available: 63 | ```php 64 | // Inside latest-news.php: 65 | have_posts() ) : $news->the_post() ?> 66 | ... 67 | 68 | 69 | ``` 70 | 71 | Here's the same example, but using a class: 72 | 73 | ```php 74 | with( [ 81 | 'news' => new WP_Query( [ 82 | 'posts_per_page' => 3, 83 | ] ), 84 | ] ); 85 | } 86 | } ); 87 | ``` 88 | And in our service provider we refer to the class instead of the anonymous function: 89 | ```php 90 | // ... 91 | public function bootstrap( $container ) { 92 | \App::views()->addComposer( 93 | 'templates/partials/latest-news', 94 | \App\ViewComposers\LatestNewsViewComposer::class 95 | ); 96 | } 97 | // ... 98 | ``` 99 | 100 | The expected method name by default is `compose` but you can use a custom one as well: 101 | ```php 102 | // ... 103 | public function bootstrap( $container ) { 104 | \App::views()->addComposer( 105 | 'templates/partials/latest-news', 106 | 'LatestNewsViewComposer@customMethodName' 107 | ); 108 | } 109 | // ... 110 | ``` 111 | 112 | By default, WP Emerge will instantiate your class directly. However, if your class is registered in the service container with its class name as the key, then the class will be resolved from the service container instead: 113 | 114 | ```php 115 | // Run this inside the register() method of a service provider. 116 | $container[ LatestNewsViewComposer::class ] = function( $container ) { 117 | // your custom instantiation code here, e.g.: 118 | return new LatestNewsViewComposer(); 119 | } 120 | ``` 121 | 122 | ## \App::render( $views, $context = [] ) 123 | 124 | Why you would use `\App::render()`: 125 | 126 | 1. You are using the default default view engine. You do not need it when using Blade or Twig, for example, as they have composition built-in. 127 | 2. Partials rendered using `include`, `require`, `get_template_part()` etc. __DO NOT__ support composition, `\App::render()` does. 128 | 3. `\App::render()` optionally provides context to the partial through the `$context` parameter. 129 | 130 | For example, instead of using 131 | ```php 132 | 133 | ``` 134 | you would use 135 | ```php 136 | 137 | ``` 138 | or instead of using 139 | ```php 140 | 141 | ``` 142 | you would use 143 | ```php 144 | 145 | ``` 146 | 147 | If you do not need composition or context for a given partial, feel free to use `get_template_part()` instead. 148 | -------------------------------------------------------------------------------- /index.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 |
2 |
3 | [](https://packagist.org/packages/htmlburger/wpemerge-plugin) [](https://github.com/htmlburger/wpemerge-plugin/actions/workflows/test.yml) [](https://gitter.im/wpemerge/Lobby)
4 |
5 |
6 | A modern WordPress starter plugin which uses the [WP Emerge](https://github.com/htmlburger/wpemerge) framework.
7 |
8 | _This is the WP Emerge Starter Plugin project - for the WP Emerge framework please check out https://github.com/htmlburger/wpemerge._
9 |
10 | ## Summary
11 |
12 | - [Documentation](#documentation)
13 | - [Development Team](#development-team)
14 | - [Comparison Table](#comparison-table)
15 | - [Features](#features)
16 | - [Non-goals](#non-goals)
17 | - [Requirements](#requirements)
18 | - [Directory structure](#directory-structure)
19 | - [Contributing](#contributing)
20 |
21 | ## Documentation
22 |
23 | [http://docs.wpemerge.com/#/starter/plugin/overview](http://docs.wpemerge.com/#/starter/plugin/overview)
24 |
25 | [http://docs.wpemerge.com/#/starter/plugin/quickstart](http://docs.wpemerge.com/#/starter/plugin/quickstart)
26 |
27 | ## Development Team
28 |
29 | Brought to you by [Atanas Angelov](https://atanas.dev/) and the lovely folks at [htmlBurger](http://htmlburger.com).
30 |
31 | ## Comparison Table
32 |
33 | | | WP Emerge Plugin | WPB | WPT |
34 | |--------------------------------|------------------|----------------|----------|
35 | | View Engine | PHP, Blade, Twig, any | PHP | PHP |
36 | | Routing | ✔ | ✖ | ✖ |
37 | | WP Admin Routing | ✔ | ✖ | ✖ |
38 | | WP AJAX Routing | ✔ | ✖ | ✖ |
39 | | MVC | ✖✔✔ | ✖✔✖ | ✖✔✖ |
40 | | Middleware | ✔ | ✖ | ✖ |
41 | | View Composers | ✔ | ✖ | ✖ |
42 | | Service Container | ✔ | ✖ | ✖ |
43 | | Stylesheets | SASS + PostCSS | CSS | LESS |
44 | | JavaScript | ES6 | Vanilla | Vanilla |
45 | | Hot reloading | ✔ | ✖ | ✖ |
46 | | Frontend/Admin/Any Bundle | ✔✔✔ | ✔✔✖¹ | ✔✔✖² |
47 | | Automatic Sprite Generation | ✔ | ✖ | ✖ |
48 | | Automatic Cache Busting | ✔ | ✖ | ✖ |
49 | | WPCS Linting | ✔ | ✖ | ✖ |
50 | | [Advanced Error Reporting](https://docs.wpemerge.com/#/framework/routing/error-handling) | ✔ | ✖ | ✖ |
51 | | WP Unit Tests for your classes | ✔ | ✖ | ✖ |
52 |
53 | _¹ There are prepared JavaScript files but they are not processed or transpiled in any way._
54 |
55 | _² The JavaScript files are only minified - no transpiling is done._
56 |
57 | _Email any factual inaccuracies to [hi@atanas.dev](mailto:hi@atanas.dev) so they can be corrected._
58 |
59 | ## Features
60 | - All features from [WP Emerge](https://docs.wpemerge.com/#/framework/overview):
61 | - Named routes with custom URLs and query filters
62 | - Controllers
63 | - Middleware
64 | - PSR-7 Responses
65 | - View Composers
66 | - Service Container
67 | - Service Providers
68 | - PHP view layouts (a.k.a. automatic wrapping)
69 | - Support for PHP, [Blade 5.4](https://laravel.com/docs/5.4/blade) and/or [Twig 2](https://twig.symfony.com/doc/2.x/api.html) for views
70 | - [SASS](https://sass-lang.com/) + [PostCSS](https://github.com/postcss/postcss) for stylesheets. Separate bundles are created for **front-end** and **administration** and custom bundles can be added easily.
71 | - ES6 for JavaScript. Separate bundles are created for **front-end** and **administration** and custom bundles can be added easily.
72 | - Pure [Webpack](https://webpack.js.org/) to transpile and bundle assets, create sprites, optimize images etc.
73 | - [Hot Module Replacement](https://webpack.js.org/concepts/hot-module-replacement/) for synchronized browser development.
74 | - Autoloading for all classes in your `MyApp\` namespace.
75 | - Automatic, fool-proof cache busting for all assets, including ones referenced in styles.
76 | - WPCS, JavaScript and SASS linting and fixing using a single yarn command.
77 | - Single-command optional CSS package installation:
78 | - Normalize.css
79 | - Boostrap 4
80 | - Bulma
81 | - Foundation
82 | - Tachyons
83 | - Tailwind CSS
84 | - Spectre.css
85 | - FontAwesome
86 | - WP Unit Test scaffolding for your own classes.
87 |
88 | ## Non-goals
89 |
90 | - Taking over the WordPress main query.
91 |
92 | WP Emerge does __not__ take over the main query - it actively works with it.
93 | - Taking over WordPress routing.
94 |
95 | WP Emerge does __not__ take over WordPress' routing - it actively works with it. The only exception to this are hardcoded URLs explicitly added by a user.
96 | - Reinventing WordPress APIs using object-oriented interfaces.
97 |
98 | WP Emerge does not provide alternative APIs for registering post types, taxonomies or the like for little added benefit. Instead, it provides logical and handy places for developers to use core APIs.
99 | - Using a third party engine by default.
100 |
101 | WP Emerge uses PHP by default in the same way WordPress does but with added features. Using a third party engine is entirely optional and requires installing an extension.
102 | - Include most of Laravel or another framework.
103 |
104 | WP Emerge is lean and tuned for WordPress. While inspired by Laravel, it does not come with any `illuminate/*` packages. There are only 2 third party production dependencies:
105 | - `pimple/pimple` - The single-file PHP service container.
106 | - `guzzlehttp/psr7` - A PSR-7 Request and ServerRequest implementation.
107 |
108 | ## Requirements
109 |
110 | - [PHP](http://php.net/) >= 5.5
111 | - [WordPress](https://wordpress.org/) >= 4.7
112 | - [Composer](https://getcomposer.org/)
113 | - [Node.js](https://nodejs.org/en/) >= 12
114 | - [Yarn](https://yarnpkg.com/en/) or NPM
115 |
116 | ## Directory structure
117 |
118 | ```
119 | wp-content/plugins/your-plugin
120 | ├── app/
121 | │ ├── helpers/ # Helper files, add your own here as well.
122 | │ ├── routes/ # Register your WP Emerge routes.
123 | │ │ ├── admin.php
124 | │ │ ├── ajax.php
125 | │ │ └── web.php
126 | │ ├── src/ # PSR-4 autoloaded classes.
127 | │ │ ├── Controllers/ # Controller classes for WP Emerge routes.
128 | │ │ ├── Routing/ # Register your custom routing conditions etc.
129 | │ │ ├── View/ # Register your view composers, globals etc.
130 | │ │ ├── WordPress/ # Register post types, taxonomies, menus etc.
131 | │ │ └── ...
132 | │ ├── config.php # WP Emerge configuration.
133 | │ ├── helpers.php # Require your helper files here.
134 | │ ├── hooks.php # Register your actions and filters here.
135 | │ └── version.php # WP Emerge version handling.
136 | ├── dist/ # Bundles, optimized images etc.
137 | ├── languages/ # Language files.
138 | ├── resources/
139 | │ ├── build/ # Build process configuration.
140 | │ ├── fonts/
141 | │ ├── images/
142 | │ ├── scripts/
143 | │ │ ├── admin/ # Administration scripts.
144 | │ │ └── frontend/ # Front-end scripts.
145 | │ ├── styles/
146 | │ │ ├── admin/ # Administration styles.
147 | │ │ ├── frontend/ # Front-end styles.
148 | │ │ └── shared/ # Shared styles.
149 | │ └── vendor/ # Any third-party, non-npm assets.
150 | ├── vendor/ # Composer packages.
151 | ├── views/
152 | │ ├── layouts/
153 | │ └── partials/
154 | ├── screenshot-1.png # Plugin screenshot.
155 | ├── wpemerge # WP Emerge CLI shortcut.
156 | ├── wpemerge.php # Bootstrap plugin.
157 | └── ...
158 | ```
159 |
160 | ### Notable directories
161 |
162 | #### `app/helpers/`
163 |
164 | Add PHP helper files here. Helper files should include __function definitions only__. See below for information on where to put actions, filters, classes etc.
165 |
166 | #### `app/src/`
167 |
168 | Add PHP class files here. All clases in the `MyApp\` namespace are autoloaded in accordance with [PSR-4](http://www.php-fig.org/psr/psr-4/).
169 |
170 | #### `resources/images/`
171 |
172 | Add images for styling here. Optimized copies will be placed in `dist/images/` when running the build process.
173 |
174 | #### `resources/styles/frontend/`
175 |
176 | Add .css and .scss files to add them to the front-end bundle. Don't forget to `@import` them in `index.scss`.
177 |
178 | #### `resources/styles/admin/`
179 |
180 | The admin styles directory which works identically to the `resources/styles/frontend/` directory.
181 |
182 | #### `resources/scripts/frontend/`
183 |
184 | Add JavaScript files here to add them to the frontend bundle. The entry point is `index.js`.
185 |
186 | #### `resources/scripts/admin/`
187 |
188 | The admin scripts directory which works identically to the `resources/scripts/frontend/` directory.
189 |
190 | #### `views/`
191 |
192 | 1. `views/layouts/` - Layouts that other views extend.
193 | 2. `views/partials/` - Small snippets that are meant to be reused throughout other views.
194 | 3. `views/` - Full page views that may extend layouts and may include partials.
195 |
196 | Avoid adding any PHP logic in any of these views, unless it pertains to layouting. Business logic should go into:
197 | - Helper files (`app/helpers/*.php`)
198 | - Service classes
199 | - [WP Emerge Controllers](https://docs.wpemerge.com/#/framework/routing/controllers)
200 |
201 | ## Contributing
202 |
203 | WP Emerge Starter Plugin is completely open source and we encourage everybody to participate by:
204 |
205 | - Reviewing `.github/CONTRIBUTING.md`.
206 | - ⭐ the project on GitHub \([https://github.com/htmlburger/wpemerge-plugin](https://github.com/htmlburger/wpemerge-plugin)\)
207 | - Posting bug reports \([https://github.com/htmlburger/wpemerge-plugin/issues](https://github.com/htmlburger/wpemerge-plugin/issues)\)
208 | - (Emailing security issues to [hi@atanas.dev](mailto:hi@atanas.dev) instead)
209 | - Posting feature suggestions \([https://github.com/htmlburger/wpemerge-plugin/issues](https://github.com/htmlburger/wpemerge-plugin/issues)\)
210 | - Posting and/or answering questions \([https://github.com/htmlburger/wpemerge-plugin/issues](https://github.com/htmlburger/wpemerge-plugin/issues)\)
211 | - Submitting pull requests \([https://github.com/htmlburger/wpemerge-plugin/pulls](https://github.com/htmlburger/wpemerge-plugin/pulls)\)
212 | - Sharing your excitement about WP Emerge with your community
213 |
--------------------------------------------------------------------------------
/starter/plugin/quickstart.md:
--------------------------------------------------------------------------------
1 | # Quickstart
2 |
3 | 1. Browse to `/wp-content/plugins`.
4 | 2. Run `composer create-project htmlburger/wpemerge-plugin PLUGIN_NAME` replacing `PLUGIN_NAME` with your desired name.
5 | 3. Run `cd wpemerge && php wpemerge install`.
6 | 4. Activate your new plugin.
7 |
8 | During the installation process you will have the option to:
9 |
10 | 1. Remove author information from `composer.json`.
11 | 2. Install Carbon Fields.
12 | 3. Install a CSS framework (Normalize.css, Bootstrap, Bulma, Foundation, Tachyons, Tailwind CSS or Spectre.css).
13 | 4. Install Font Awesome.
14 |
15 | ?> The starter plugin comes with a placeholder namespace, functions and constants prefix - `\MyApp`, `my_app` and `MY_APP` respectively.
16 |
17 | To change these prefixes, you can run `yarn rebrand` inside the plugin directory - it will ask you a couple of questions and automatically rename everything for you.
18 |
19 | Let's say you've chosen `AwesomePlugin` as your namespace during the `yarn rebrand` process. What this means is that instead of `\MyApp` you must now use `\AwesomePlugin`:
20 | - `\MyApp::render()` becomes `\AwesomePlugin::render()`.
21 | - `my_app_get_title()` becomes `awesome_plugin_get_title()`.
22 | - etc.
23 |
24 | ## Quickstart on Bedrock
25 |
26 | 1. Browse to your [Bedrock](https://roots.io/bedrock/) root directory.
27 | 2. Run `composer require htmlburger/wpemerge-plugin:0.17.1`.
28 | 3. Run `composer require --dev htmlburger/wpemerge-cli`.
29 | 4. Run `(cd web/app/plugins/wpemerge-plugin && composer run install-dev-env && php wpemerge install)`.
30 | 5. Activate your new plugin.
31 |
--------------------------------------------------------------------------------
/starter/plugin/what-goes-where.md:
--------------------------------------------------------------------------------
1 | # What goes where
2 |
3 | Starting a new project can be overwhelming as every feature has its cognitive cost. Even the basic act of navigating through a codebase and knowing what goes where can be a challenge. That is why this handy guide will point you to the right place to do everything.
4 |
5 | ?> If you feel comfortable with service providers, you can split up self-contained logical modules into their own `app/src/*/` directories with their own service providers which register services, post types, taxonomies, actions, filters etc. instead of using the common places listed below. __This approach can make your code more reusable and testable but it is not mandatory__.
6 |
7 | ## One-off functions
8 |
9 | ?> `/app/helpers/{relevant-filename}.php`
10 |
11 | The best place to add a simple function would be in a suitable file inside the `helpers` directory. If such a file does not exist don't be afraid to add one yourself, just make sure you `require_once` the new file in `app/helpers.php`.
12 |
13 | ## One-off actions and filters
14 |
15 | ?> `/app/hooks.php`
16 |
17 | The bast place to add simple actions or filters is the dedicated `hooks.php` file. Avoid defining functions here - use `add_action()` and `add_filter()` only.
18 |
19 | ## Views (templates)
20 |
21 | ?> `/views/`
22 |
23 | Templates that don't fit anywhere else go here.
24 |
25 | ?> `/views/layouts/`
26 |
27 | Layouts that other templates extend via the `Layout` file header comment go here.
28 |
29 | ?> `/views/partials/`
30 |
31 | Small template snippets that are meant to be reused throughout other templates go here.
32 |
33 | ## Styles
34 |
35 | ?> `/resources/styles/[frontend|admin]/`
36 |
37 | Styles for the frontend and admin go in the respective directory.
38 | Since the starter plugin uses SASS you can add as many files as you need and import them in the main `index.scss` file (or any other file that is imported in it) and they will be bundled up into a single optimized CSS file. You can even include them via a wildcard (e.g. `@import './module-*.scss';`).
39 |
40 | ## Scripts
41 |
42 | ?> `/resources/scripts/[frontend|admin]/`
43 |
44 | Scripts for the frontend and admin go in the respective directory.
45 | Since the starter plugin uses Webpack you can add as many files as you need and include them in the main `index.js` file (or any other file that is included in it) and they will be bundled up into a single optimized JS file. You can even include them via a wildcard (e.g. `import './modules/*.js';`).
46 |
47 | ## Images
48 |
49 | Images that are part of your site's content, such as blog post featured images, site logo etc. should be uploaded to your Media library. Other images go into:
50 |
51 | ?> `/resources/images/`
52 |
53 | For images that are necessary for styling purposes, backgrounds etc.
54 |
55 | ?> `/resources/images/sprite/`
56 |
57 | For images that are going to be bundled into a single [raster sprite](/starter/assets/sprites.md?id=raster-sprite).
58 |
59 | ?> `/resources/images/sprite-svg/`
60 |
61 | For SVG files that are going to be bundled into a single [SVG sprite](/starter/assets/sprites.md?id=svg-sprite).
62 |
63 | ## Fonts
64 |
65 | ?> `/resources/fonts/`
66 |
67 | Self-hosted fonts go here. You can reference a font stored in this directory via the `~@fonts/` [alias](/starter/assets/overview?id=importing-assets) when using a `@font-face` declaration.
68 |
69 | ## WordPress Admin Pages
70 |
71 | ?> `/app/src/WordPress/AdminServiceProvider.php`
72 |
73 | Any calls to `add_menu_page()`, `add_submenu_page()` etc. go here.
74 |
75 | ## Enqueueing scripts and styles
76 |
77 | ?> `/app/src/WordPress/AssetsServiceProvider.php`
78 |
79 | ## Custom post types and taxonomies
80 |
81 | ?> `/app/src/WordPress/ContentTypesServiceProvider.php`
82 |
83 | ## Plugin activation/deactivation actions
84 |
85 | ?> `/app/src/WordPress/PluginServiceProvider.php`
86 |
87 | ## Shortcodes
88 |
89 | ?> `/app/src/WordPress/ShortcodesServiceProvider.php`
90 |
91 | Bonus points: You may want to create a new `views/shortcodes/` directory and add your shortcodes as `.php` files inside it which your shortcode service provider can return like this:
92 | ```php
93 | function shortcodeExample( $atts, $content ) {
94 | $atts = shortcode_atts(
95 | array(
96 | 'example_attribute' => 'example_value',
97 | ),
98 | $atts,
99 | 'example'
100 | );
101 |
102 | return \App::view( 'views/shortcodes/my-shortcode.php' )
103 | ->with( $atts )
104 | ->with( 'content', $content )
105 | ->toString();
106 | }
107 | ```
108 |
109 | ## Widgets
110 |
111 | ?> `/app/src/WordPress/WidgetsServiceProvider.php`
112 |
113 | ## Custom classes, controllers, middleware etc.
114 |
115 | ?> `/app/src/*`
116 |
117 | Custom classes are autoloaded according to PSR-4 so make sure you name them correctly and place them in the directory that is appropriate to their namespace e.g.:
118 |
119 | | Class | File |
120 | |----------------------------- |---------------------------------- |
121 | | `App\MyClass` | `app/MyClass.php` |
122 | | `App\Controllers\Web\Home` | `app/Controllers/Web/Home.php` |
123 | | `App\ViewComposers\UserBadge` | `app/ViewComposers/UserBadge.php` |
124 |
125 | You can find more information about PSR-4 autoloading at http://www.php-fig.org/psr/psr-4/
126 |
--------------------------------------------------------------------------------
/starter/publishing.md:
--------------------------------------------------------------------------------
1 | # Publishing
2 |
3 | Here are the general steps you need to follow when you are ready to publish your plugin or theme.
4 |
5 | 1. Make sure you've ran `yarn rebrand` to replace all `MyApp` placeholders with ones that match your project name. __Always make sure you have a backup of your files before running the rebrand command!__
6 | 2. Run `yarn i18n` to update all usages of i18n functions (`__()`, `_e()` etc.) in your source files and to update your language files with all strings referenced in your source files.
7 | 3. If you have any files outside of the default directories that you wish to publish with your plugin or theme make sure they are present in the `release.include` key of your `config.json` file:
8 | ```json
9 | "release": {
10 | "configWhitelist": [
11 | "variables"
12 | ],
13 | "include": [
14 | "app/",
15 | "dist/",
16 | "languages/",
17 | "vendor/",
18 | "views/",
19 | "config.json",
20 | "LICENSE",
21 | "README.md",
22 | "readme.txt",
23 | "screenshot.png",
24 | "style.css",
25 | "*.php"
26 | ]
27 | }
28 | ```
29 | 4. Run [`yarn release`](starter/scripts/overview#yarn-release) - this will produce a `themes/your-theme.zip` archive ready for distribution.
30 |
--------------------------------------------------------------------------------
/starter/scripts.md:
--------------------------------------------------------------------------------
1 | # Scripts
2 |
3 | ## `yarn start`
4 |
5 | Run the build process in development mode:
6 | - Transpile modern JavaScript syntax based on Stage 2 proposals and the `browserslist` key in `package.json`.
7 | - Compile SCSS into CSS.
8 | - Combine CSS media queries to reduce stylesheet size.
9 | - Process CSS through Autoprefixer.
10 | - Generate a `manifest.json` file with automatic filename-based asset cache busting.
11 | - Bundle images in `resources/images/sprite/` into a single sprite image, with optional @2x version.
12 |
13 | ## `yarn hot`
14 |
15 | Run the build process in hot mode which is identical to development mode but also automatically reloads your browser as you make changes. Modules processed by a Webpack loader that supports HMR (e.g. CSS via `style-loader`) will be injected via HMR avoiding a full page reload.
16 |
17 | ## `yarn build`
18 |
19 | Run the build process in production mode with Webpack optimizations enabled:
20 | - Transpile modern JavaScript syntax based on Stage 2 proposals and the `browserslist` key in `package.json`.
21 | - **Minify JavaScript.**
22 | - Compile SCSS into CSS.
23 | - Combine CSS media queries to reduce stylesheet size.
24 | - Process CSS through Autoprefixer.
25 | - **Minify CSS.**
26 | - Generate a `manifest.json` file with automatic filename-based asset cache busting.
27 | - Bundle images in `resources/images/sprite/` into a single sprite image, with optional @2x version.
28 | - **Optimize images to reduce filesize.**
29 |
30 | ?> Non-minified versions of JavaScript and CSS assets will also be generated in build mode in order to support WordPress' SCRIPT_DEBUG mode.
31 |
32 | ## `yarn rebrand`
33 |
34 | Rewrites your files to use a new project name, namespace, constant and function prefix. For example:
35 | - `namespace \MyApp\*;`
36 | - `function my_app_*() {};`
37 | - `define( 'MY_APP_*', '*' );`
38 |
39 | ?> The `rebrand` command is rudimentary and only meant to be used once per project.
40 |
41 | !> The `rebrand` command is potentially destructive - make sure you have committed and backed up your files before running it.
42 |
43 | ## `yarn release`
44 |
45 | Creates a production-ready zip of your plugin or theme. Running `yarn release` will:
46 | 1. Run `yarn build`.
47 | 2. Create a new temporary directory.
48 | 3. Copy all files and directories specified in the `release.include` key of your `config.json` file.
49 | - By default, this list contains all necessary files for your plugin or theme.
50 | - If you have any custom files/directories outside of the standard directories make sure to add them to this list.
51 | 4. Install production-only Composer dependencies with an authoritative classmap for improved autoloading performance.
52 | 5. Create a zip file e.g. `themes/your-theme.zip` ready for distribution.
53 |
54 | ## `yarn lint`
55 |
56 | Run the php, scripts and styles linters (`WPCS`, `eslint` and `stylelint` respectively), reporting any lint rule violations.
57 |
58 | ## `yarn lint-fix`
59 |
60 | Run the php, scripts and styles linters (`WPCS`, `eslint` and `stylelint` respectively), fixing any fixable lint rule violations.
61 |
62 | ## `yarn i18n`
63 |
64 | Runs both `yarn i18n:textdomain` and `i18n:pot`.
65 |
66 | #### `yarn i18n:textdomain`
67 |
68 | Runs the `textdomain` command of the [node-wp-i18n](https://www.npmjs.com/package/node-wp-i18n) package, adding a text domain to all gettext function calls throughout your code.
69 |
70 | #### `yarn i18n:pot`
71 |
72 | Runs the `makepot` command of the [node-wp-i18n](https://www.npmjs.com/package/node-wp-i18n) package, generating your `languages/my_app.pot` file based on all gettext function calls throughout your code.
73 |
74 | ## Webpack Dev Server
75 |
76 | In `yarn hot` mode, Webpack Dev Server will setup a simple web server and serve changes to your assets as you work on them. If your website is setup inside a virtual machine and you are running `yarn hot` inside that virtual machine you will have to change your `development.hotUrl` option in your `config.json` file as otherwise WP Emerge will assume you are running it on your localhost.
77 |
78 | To let WP Emerge know where you run `yarn hot`, open up `config.json` from the root directory of your plugin or theme and edit the `development.hotUrl` key like this:
79 | ```json
80 | {
81 | "development": {
82 | "hotUrl": "http://my-virtual-machine.test/"
83 | // ...
84 | }
85 | // ...
86 | }
87 | ```
88 | Save the file and restart your development build process by running `yarn hot`.
89 |
--------------------------------------------------------------------------------
/starter/theme/overview.md:
--------------------------------------------------------------------------------
1 | # 
2 |
3 | [](https://packagist.org/packages/htmlburger/wpemerge-theme) [](https://github.com/htmlburger/wpemerge-theme/actions/workflows/test.yml) [](https://gitter.im/wpemerge/Lobby)
4 |
5 |
6 | A modern WordPress starter theme which uses the [WP Emerge](https://github.com/htmlburger/wpemerge) framework.
7 |
8 | _This is the WP Emerge Starter Theme project - for the WP Emerge framework please check out https://github.com/htmlburger/wpemerge._
9 |
10 | ## Summary
11 |
12 | - [Documentation](#documentation)
13 | - [Development Team](#development-team)
14 | - [Comparison Table](#comparison-table)
15 | - [Features](#features)
16 | - [Non-goals](#non-goals)
17 | - [Requirements](#requirements)
18 | - [Directory structure](#directory-structure)
19 | - [Contributing](#contributing)
20 |
21 | ## Documentation
22 |
23 | [http://docs.wpemerge.com/#/starter/theme/overview](http://docs.wpemerge.com/#/starter/theme/overview)
24 |
25 | [http://docs.wpemerge.com/#/starter/theme/quickstart](http://docs.wpemerge.com/#/starter/theme/quickstart)
26 |
27 | ## Development Team
28 |
29 | Brought to you by [Atanas Angelov](https://atanas.dev/) and the lovely folks at [htmlBurger](http://htmlburger.com).
30 |
31 | ## Comparison Table
32 |
33 | | | WP Emerge Theme | Sage | Timber |
34 | |--------------------------------|------------------|----------------|----------|
35 | | View Engine | PHP, Blade, Twig, any | PHP, Blade | Twig |
36 | | Routing | ✔ | ✖ | ✔ |
37 | | WP Admin Routing | ✔ | ✖ | ✖ |
38 | | WP AJAX Routing | ✔ | ✖ | ✖ |
39 | | MVC | ✖✔✔ | ✖✔✖¹ | ✖✔✖ |
40 | | Middleware | ✔ | ✖ | ✖ |
41 | | View Composers | ✔ | ✔/✖² | ✖ |
42 | | Service Container | ✔ | ✔ | ✖ |
43 | | Stylesheets | SASS + PostCSS | SASS + PostCSS | N/A³ |
44 | | JavaScript | ES6 | ES6 | N/A³ |
45 | | Front end, Admin, Editor and Login Bundles | ✔✔✔✔ | ✔✖✖✖ | N/A³ |
46 | | Automatic Sprite Generation | ✔ | ✖ | N/A³ |
47 | | Automatic Cache Busting | ✔ | ✖ | ✖ |
48 | | WPCS Linting | ✔ | ✖ | ✖ |
49 | | [Advanced Error Reporting](https://docs.wpemerge.com/#/framework/routing/error-handling) | ✔ | ✖ | ✖ |
50 | | WP Unit Tests for your classes | ✔ | ✖ | ✖ |
51 |
52 | _¹ Sage's Controller is more of a View Composer than a Controller._
53 |
54 | _² Sage's Controller provides similar functionality but is limited to 1 composer (controller) per view and vice versa._
55 |
56 | _³ Timber does not provide a front-end build process so you can implement whatever you prefer._
57 |
58 | _Email any factual inaccuracies to [hi@atanas.dev](mailto:hi@atanas.dev) so they can be corrected._
59 |
60 | ## Features
61 | - All features from [WP Emerge](https://docs.wpemerge.com/#/framework/overview):
62 | - Named routes with custom URLs and query filters
63 | - Controllers
64 | - Middleware
65 | - PSR-7 Responses
66 | - View Composers
67 | - Service Container
68 | - Service Providers
69 | - PHP view layouts (a.k.a. automatic wrapping)
70 | - Support for PHP, [Blade 5.4](https://laravel.com/docs/5.4/blade) and/or [Twig 2](https://twig.symfony.com/doc/2.x/api.html) for views
71 | - Gutenberg support.
72 | - [SASS](https://sass-lang.com/) + [PostCSS](https://github.com/postcss/postcss) for stylesheets. Separate bundles are created for **front-end**, **administration**, **Gutenberg** and **login** pages and custom bundles can be added easily.
73 | - ES6 for JavaScript. Separate bundles are created for **front-end**, **administration**, **Gutenberg** and **login** pages and custom bundles can be added easily.
74 | - Pure [Webpack](https://webpack.js.org/) to transpile and bundle assets, create sprites, optimize images etc.
75 | - [Hot Module Replacement](https://webpack.js.org/concepts/hot-module-replacement/) for synchronized browser development.
76 | - Autoloading for all classes in your `MyApp\` namespace.
77 | - Automatic, fool-proof cache busting for all assets, including ones referenced in styles.
78 | - WPCS, JavaScript and SASS linting and fixing using a single yarn command.
79 | - Single-command optional CSS package installation:
80 | - Normalize.css
81 | - Boostrap 4
82 | - Bulma
83 | - Foundation
84 | - Tachyons
85 | - Tailwind CSS
86 | - Spectre.css
87 | - FontAwesome
88 | - WP Unit Test scaffolding for your own classes.
89 |
90 | ## Non-goals
91 |
92 | - Taking over the WordPress main query.
93 |
94 | WP Emerge does __not__ take over the main query - it actively works with it.
95 | - Taking over WordPress routing.
96 |
97 | WP Emerge does __not__ take over WordPress' routing - it actively works with it. The only exception to this are hardcoded URLs explicitly added by a user.
98 | - Reinventing WordPress APIs using object-oriented interfaces.
99 |
100 | WP Emerge does not provide alternative APIs for registering post types, taxonomies or the like for little added benefit. Instead, it provides logical and handy places for developers to use core APIs.
101 | - Using a third party engine by default.
102 |
103 | WP Emerge uses PHP by default in the same way WordPress does but with added features. Using a third party engine is entirely optional and requires installing an extension.
104 | - Include most of Laravel or another framework.
105 |
106 | WP Emerge is lean and tuned for WordPress. While inspired by Laravel, it does not come with any `illuminate/*` packages. There are only 2 third party production dependencies:
107 | - `pimple/pimple` - The single-file PHP service container.
108 | - `guzzlehttp/psr7` - A PSR-7 Request and ServerRequest implementation.
109 |
110 | ## Requirements
111 |
112 | - [PHP](http://php.net/) >= 5.5
113 | - [WordPress](https://wordpress.org/) >= 4.7
114 | - [Composer](https://getcomposer.org/)
115 | - [Node.js](https://nodejs.org/en/) >= 12
116 | - [Yarn](https://yarnpkg.com/en/) or NPM
117 |
118 | ## Directory structure
119 |
120 | ```
121 | wp-content/themes/your-theme
122 | ├── app/
123 | │ ├── helpers/ # Helper files, add your own here as well.
124 | │ ├── routes/ # Register your WP Emerge routes.
125 | │ │ ├── admin.php
126 | │ │ ├── ajax.php
127 | │ │ └── web.php
128 | │ ├── src/ # PSR-4 autoloaded classes.
129 | │ │ ├── Controllers/ # Controller classes for WP Emerge routes.
130 | │ │ ├── Routing/ # Register your custom routing conditions etc.
131 | │ │ ├── View/ # Register your view composers, globals etc.
132 | │ │ ├── WordPress/ # Register post types, taxonomies, menus etc.
133 | │ │ └── ...
134 | │ ├── config.php # WP Emerge configuration.
135 | │ ├── helpers.php # Require your helper files here.
136 | │ ├── hooks.php # Register your actions and filters here.
137 | │ └── version.php # WP Emerge version handling.
138 | ├── dist/ # Bundles, optimized images etc.
139 | ├── languages/ # Language files.
140 | ├── resources/
141 | │ ├── build/ # Build process configuration.
142 | │ ├── fonts/
143 | │ ├── images/
144 | │ ├── scripts/
145 | │ │ ├── admin/ # Administration scripts.
146 | │ │ ├── editor/ # Gutenberg editor scripts.
147 | │ │ ├── login/ # Login scripts.
148 | │ │ └── frontend/ # Front-end scripts.
149 | │ ├── styles/
150 | │ │ ├── admin/ # Administration styles.
151 | │ │ ├── editor/ # Gutenberg editor styles.
152 | │ │ ├── login/ # Login styles.
153 | │ │ ├── frontend/ # Front-end styles.
154 | │ │ └── shared/ # Shared styles.
155 | │ └── vendor/ # Any third-party, non-npm assets.
156 | ├── vendor/ # Composer packages.
157 | ├── views/
158 | │ ├── layouts/
159 | │ └── partials/
160 | ├── views-alternatives/ # Views for other engines like Blade.
161 | ├── functions.php # Bootstrap theme.
162 | ├── screenshot.png # Theme screenshot.
163 | ├── style.css # Theme stylesheet.
164 | ├── wpemerge # WP Emerge CLI shortcut.
165 | └── ...
166 | ```
167 |
168 | ### Notable directories
169 |
170 | #### `app/helpers/`
171 |
172 | Add PHP helper files here. Helper files should include __function definitions only__. See below for information on where to put actions, filters, classes etc.
173 |
174 | #### `app/src/`
175 |
176 | Add PHP class files here. All clases in the `MyApp\` namespace are autoloaded in accordance with [PSR-4](http://www.php-fig.org/psr/psr-4/).
177 |
178 | #### `resources/images/`
179 |
180 | Add images for styling here. Optimized copies will be placed in `dist/images/` when running the build process.
181 |
182 | #### `resources/styles/frontend/`
183 |
184 | Add .css and .scss files to add them to the front-end bundle. Don't forget to `@import` them in `index.scss`.
185 |
186 | #### `resources/styles/[admin,editor,login]/`
187 |
188 | These directories are for the admin, editor and login bundles, respectively. They work identically to the main `resources/styles/frontend/` directory.
189 |
190 | #### `resources/scripts/frontend/`
191 |
192 | Add JavaScript files here to add them to the frontend bundle. The entry point is `index.js`.
193 |
194 | #### `resources/scripts/[admin,editor,login]/`
195 |
196 | These directories are for the admin, editor and login bundles, respectively. They work identically to the main `resources/scripts/frontend/` directory.
197 |
198 | #### `views/`
199 |
200 | While views that follow the WordPress template hierarchy should go in the theme root directory (e.g. `index.php`, `searchform.php`, `archive-post.php` etc.), others should go in the following directories:
201 | 1. `views/layouts/` - Layouts that other views extend.
202 | 2. `views/partials/` - Small snippets that are meant to be reused throughout other views.
203 | 3. `views/` - Named [custom post templates](https://developer.wordpress.org/themes/template-files-section/page-template-files/#creating-custom-page-templates-for-global-use) or views that don't fit anywhere else.
204 |
205 | Avoid adding any PHP logic in any of these views, unless it pertains to layouting. Business logic should go into:
206 | - Helper files (`app/helpers/*.php`)
207 | - Service classes
208 | - [WP Emerge Controllers](https://docs.wpemerge.com/#/framework/routing/controllers)
209 |
210 | ## Contributing
211 |
212 | WP Emerge Starter Theme is completely open source and we encourage everybody to participate by:
213 |
214 | - Reviewing `.github/CONTRIBUTING.md`.
215 | - ⭐ the project on GitHub \([https://github.com/htmlburger/wpemerge-theme](https://github.com/htmlburger/wpemerge-theme)\)
216 | - Posting bug reports \([https://github.com/htmlburger/wpemerge-theme/issues](https://github.com/htmlburger/wpemerge-theme/issues)\)
217 | - (Emailing security issues to [hi@atanas.dev](mailto:hi@atanas.dev) instead)
218 | - Posting feature suggestions \([https://github.com/htmlburger/wpemerge-theme/issues](https://github.com/htmlburger/wpemerge-theme/issues)\)
219 | - Posting and/or answering questions \([https://github.com/htmlburger/wpemerge-theme/issues](https://github.com/htmlburger/wpemerge-theme/issues)\)
220 | - Submitting pull requests \([https://github.com/htmlburger/wpemerge-theme/pulls](https://github.com/htmlburger/wpemerge-theme/pulls)\)
221 | - Sharing your excitement about WP Emerge with your community
222 |
--------------------------------------------------------------------------------
/starter/theme/quickstart.md:
--------------------------------------------------------------------------------
1 | # Quickstart
2 |
3 | 1. Browse to `/wp-content/themes`.
4 | 2. Run `composer create-project htmlburger/wpemerge-theme THEME_NAME` replacing `THEME_NAME` with your desired name.
5 | 3. Run `cd wpemerge && php wpemerge install`.
6 | 4. Activate your new theme.
7 |
8 | During the installation process you will have the option to:
9 |
10 | 1. Remove author information from `composer.json`.
11 | 2. Install Carbon Fields.
12 | 3. Install a CSS framework (Normalize.css, Bootstrap, Bulma, Foundation, Tachyons, Tailwind CSS or Spectre.css).
13 | 4. Install Font Awesome.
14 |
15 | ?> The starter theme comes with a placeholder namespace, functions and constants prefix - `\MyApp`, `my_app` and `MY_APP` respectively.
16 |
17 | To change these prefixes, you can run `yarn rebrand` inside the theme directory - it will ask you a couple of questions and automatically rename everything for you.
18 |
19 | Let's say you've chosen `AwesomeTheme` as your namespace during the `yarn rebrand` process. What this means is that instead of `\MyApp` you must now use `\AwesomeTheme`:
20 | - `\MyApp::render()` becomes `\AwesomeTheme::render()`.
21 | - `my_app_get_title()` becomes `awesome_theme_get_title()`.
22 | - etc.
23 |
24 | ## Quickstart on Bedrock
25 |
26 | 1. Browse to your [Bedrock](https://roots.io/bedrock/) root directory.
27 | 2. Run `composer require htmlburger/wpemerge-theme:0.17.1`.
28 | 3. Run `composer require --dev htmlburger/wpemerge-cli`.
29 | 4. Run `(cd web/app/themes/wpemerge-theme && composer run install-dev-env && php wpemerge install)`.
30 | 5. Activate your new theme.
31 |
--------------------------------------------------------------------------------
/starter/theme/what-goes-where.md:
--------------------------------------------------------------------------------
1 | # What goes where
2 |
3 | Starting a new project can be overwhelming as every feature has its cognitive cost. Even the basic act of navigating through a codebase and knowing what goes where can be a challenge. That is why this handy guide will point you to the right place to do everything.
4 |
5 | ?> If you feel comfortable with service providers, you can split up self-contained logical modules into their own `app/src/*/` directories with their own service providers which register services, post types, taxonomies, actions, filters etc. instead of using the common places listed below. __This approach can make your code more reusable and testable but it is not mandatory__.
6 |
7 | ## One-off functions
8 |
9 | ?> `/app/helpers/{relevant-filename}.php`
10 |
11 | The best place to add a simple function would be in a suitable file inside the `helpers` directory. If such a file does not exist don't be afraid to add one yourself, just make sure you `require_once` the new file in `app/helpers.php`.
12 |
13 | ## One-off actions and filters
14 |
15 | ?> `/app/hooks.php`
16 |
17 | The bast place to add simple actions or filters is the dedicated `hooks.php` file. Avoid defining functions here - use `add_action()` and `add_filter()` only.
18 |
19 | ## Views (templates)
20 |
21 | ?> `/` (theme root)
22 |
23 | WordPress core templates such as `header.php`, `index.php` etc. go here.
24 |
25 | ?> `/views/`
26 |
27 | Named [custom post templates](https://developer.wordpress.org/themes/template-files-section/page-template-files/#creating-custom-page-templates-for-global-use) or templates that don't fit anywhere else go here.
28 |
29 | ?> `/views/layouts/`
30 |
31 | Layouts that other templates extend via the `Layout` file header comment go here.
32 |
33 | ?> `/views/partials/`
34 |
35 | Small template snippets that are meant to be reused throughout other templates go here.
36 |
37 | ## Styles
38 |
39 | ?> `/resources/styles/[frontend|admin|login|editor]/`
40 |
41 | Styles for the frontend, admin, login and editor go in the respective directory.
42 | Since the starter theme uses SASS you can add as many files as you need and import them in the main `index.scss` file (or any other file that is imported in it) and they will be bundled up into a single optimized CSS file. You can even include them via a wildcard (e.g. `@import './module-*.scss';`).
43 |
44 | ## Scripts
45 |
46 | ?> `/resources/scripts/[frontend|admin|login|editor]/`
47 |
48 | Scripts for the frontend, admin, login and editor go in the respective directory.
49 | Since the starter theme uses Webpack you can add as many files as you need and include them in the main `index.js` file (or any other file that is included in it) and they will be bundled up into a single optimized JS file. You can even include them via a wildcard (e.g. `import './modules/*.js';`).
50 |
51 | ## Images
52 |
53 | Images that are part of your site's content, such as blog post featured images, site logo etc. should be uploaded to your Media library. Other images go into:
54 |
55 | ?> `/resources/images/`
56 |
57 | For images that are necessary for styling purposes, backgrounds etc.
58 |
59 | ?> `/resources/images/sprite/`
60 |
61 | For images that are going to be bundled into a single [raster sprite](/starter/assets/sprites.md?id=raster-sprite).
62 |
63 | ?> `/resources/images/sprite-svg/`
64 |
65 | For SVG files that are going to be bundled into a single [SVG sprite](/starter/assets/sprites.md?id=svg-sprite).
66 |
67 | ## Fonts
68 |
69 | ?> `/resources/fonts/`
70 |
71 | Self-hosted fonts go here. You can reference a font stored in this directory via the `~@fonts/` [alias](/starter/assets/overview?id=importing-assets) when using a `@font-face` declaration.
72 |
73 | ## WordPress Admin Pages
74 |
75 | ?> `/app/src/WordPress/AdminServiceProvider.php`
76 |
77 | Any calls to `add_menu_page()`, `add_theme_page()` etc. go here.
78 |
79 | ## Enqueueing scripts and styles
80 |
81 | ?> `/app/src/WordPress/AssetsServiceProvider.php`
82 |
83 | ## Custom post types and taxonomies
84 |
85 | ?> `/app/src/WordPress/ContentTypesServiceProvider.php`
86 |
87 | ## Menu locations
88 |
89 | ?> `/app/src/WordPress/MenusServiceProvider.php`
90 |
91 | ## Shortcodes
92 |
93 | ?> `/app/src/WordPress/ShortcodesServiceProvider.php`
94 |
95 | Bonus points: You may want to create a new `views/shortcodes/` directory and add your shortcodes as `.php` files inside it which your shortcode service provider can return like this:
96 | ```php
97 | function shortcodeExample( $atts, $content ) {
98 | $atts = shortcode_atts(
99 | array(
100 | 'example_attribute' => 'example_value',
101 | ),
102 | $atts,
103 | 'example'
104 | );
105 |
106 | return \App::view( 'views/shortcodes/my-shortcode.php' )
107 | ->with( $atts )
108 | ->with( 'content', $content )
109 | ->toString();
110 | }
111 | ```
112 |
113 | ## Theme support
114 |
115 | ?> `/app/src/WordPress/ThemeServiceProvider.php`
116 |
117 | ## Widgets and sidebars
118 |
119 | ?> `/app/src/WordPress/WidgetsServiceProvider.php`
120 |
121 | ## Custom classes, controllers, middleware etc.
122 |
123 | ?> `/app/src/*`
124 |
125 | Custom classes are autoloaded according to PSR-4 so make sure you name them correctly and place them in the directory that is appropriate to their namespace e.g.:
126 |
127 | | Class | File |
128 | |----------------------------- |---------------------------------- |
129 | | `App\MyClass` | `app/MyClass.php` |
130 | | `App\Controllers\Web\Home` | `app/Controllers/Web/Home.php` |
131 | | `App\ViewComposers\UserBadge` | `app/ViewComposers/UserBadge.php` |
132 |
133 | You can find more information about PSR-4 autoloading at http://www.php-fig.org/psr/psr-4/
134 |
--------------------------------------------------------------------------------
/starter/utilities/assets.md:
--------------------------------------------------------------------------------
1 | # \MyApp::core()->assets()
2 |
3 | This utility provides tools to work with assets.
4 |
5 | `\MyApp::core()->assets()->getUrl()`
6 |
7 | Return the public URL of the plugin or theme root directory.
8 |
9 | `\MyApp::core()->assets()->getAssetUrl( $asset )`
10 |
11 | Get the real absolute URL to an asset that was built using the Webpack pipeline.
12 |
13 | Assets such as images and fonts which pass through the build pipeline have their content hashed and appended to their filenames to facilitate cache busting. Since filenames change depending on the contents, a `dist/manifest.json` file is **automatically** generated to act as a map between the source filename and the final filename which includes said hash.
14 |
15 | Having this `dist/manifest.json`:
16 | ```json
17 | {
18 | // ...
19 | "images/favicon.ico": "images/favicon.3bb5e12219.ico",
20 | // ...
21 | }
22 | ```
23 | ... calling the following in your theme:
24 | ```php
25 | \MyApp::core()->assets()->getAssetUrl( 'images/favicon.ico' )
26 | ```
27 | ... will return:
28 | ```
29 | https://example.org/wp-content/themes/my-theme/dist/images/favicon.3bb5e12219.ico
30 | ```
31 |
32 | You can see this exact scenario used for the `\MyApp::core()->assets()->addFavicon()` method here:
33 |
34 | https://github.com/htmlburger/wpemerge-app-core/blob/master/src/Assets/Assets.php#L159
35 |
36 | `\MyApp::core()->assets()->getBundleUrl( $name, $extension )`
37 |
38 | Get the URL for the given JavaScript or CSS bundle.
39 | This utility takes care of returning the correct bundle URL based on whether a production bundle exists, SCRIPT_DEBUG is enabled or the bundles are currently being served in hot mode.
40 |
41 | Example:
42 | ```php
43 | // Enqueue scripts.
44 | \MyApp::core()->assets()->enqueueScript(
45 | 'my-js-bundle',
46 | \MyApp::core()->assets()->getBundleUrl( 'frontend', '.js' ),
47 | [ 'jquery' ],
48 | true
49 | );
50 |
51 | // Enqueue styles.
52 | $style = \MyApp::core()->assets()->getBundleUrl( 'frontend', '.css' );
53 |
54 | if ( $style ) {
55 | // A style bundle is not created in hot mode as it is injected via JavaScript
56 | // so we skip enqueueing it if it does not exist.
57 | \MyApp::core()->assets()->enqueueStyle(
58 | 'my-css-bundle',
59 | $style
60 | );
61 | }
62 | ```
63 |
64 | `\MyApp::core()->assets()->enqueueStyle( $handle, $src, $dependencies = [], $media = 'all' )`
65 |
66 | Enqueue a style like `wp_enqueue_style()` does but provide an automatic version number derived from the file's modified time.
67 |
68 | Essentially provide a built-in, automatic and fool-proof cache buster for the enqueued style.
69 |
70 | `\MyApp::core()->assets()->enqueueScript( $handle, $src, $dependencies = [], $in_footer = false )`
71 |
72 | Enqueue a script like `wp_enqueue_script()` does but provide an automatic version number derived from the file's modified time.
73 |
74 | Essentially provide a built-in, automatic and fool-proof cache buster for the enqueued script.
75 |
76 | `\MyApp::core()->assets()->addFavicon()`
77 |
78 | Output a <link /> tag for the site favicon pointing to `dist/images/favicon.ico` which is generated by default from `resources/images/favicon.ico`.
79 |
80 | Will not output anything if you have already added a favicon through WordPress' Customizer so it does not override it.
81 |
--------------------------------------------------------------------------------
/starter/utilities/avatar.md:
--------------------------------------------------------------------------------
1 | # \MyApp::core()->avatar()
2 |
3 | This utility provides tools to work with custom user avatars.
4 |
5 | `\MyApp::core()->avatar()->setDefault( $attachment_id )`
6 |
7 | Register an attachment as the default avatar for users on the site.
8 |
9 | `\MyApp::core()->avatar()->addUserMetaKey( $user_meta_key )`
10 |
11 | Register a user meta key as a possible avatar for users.
12 | When an avatar is fetched, it will check all registered user meta keys for a valid attachment id value and will use that as the avatar for the user - this way you can provide users with the ability to upload a custom avatar instead of relying on Gravatars or custom plugins for this functionality.
13 |
14 | `\MyApp::core()->avatar()->removeUserMetaKey( $user_meta_key )`
15 |
16 | Unregister a user meta key as a possible avatar for users.
17 |
--------------------------------------------------------------------------------
/starter/utilities/config.md:
--------------------------------------------------------------------------------
1 | # \MyApp::core()->config()
2 |
3 | This utility provides tools to work with the project's `config.json` file.
4 |
5 | `\MyApp::core()->config()->get( $key, $default = null )`
6 |
7 | Return the specified config key using dot notation or the specified default if the key is not set.
8 |
9 | Example:
10 | ```json
11 | {
12 | foo: {
13 | bar: {
14 | baz: 'foobarbaz'
15 | }
16 | }
17 | }
18 | ```
19 | To get `baz` you would use `\MyApp::core()->config()->get( 'foo.bar.baz' )`.
20 |
--------------------------------------------------------------------------------
/starter/utilities/image.md:
--------------------------------------------------------------------------------
1 | # \MyApp::core()->image()
2 |
3 | This utility provides tools to work with images.
4 |
5 | `\MyApp::core()->image()->thumbnail( $attachment_id, $width, $height, $crop = true )`
6 |
7 | Generate and cache a thumbnail for the passed attachment id. Uses WordPress' built-in image editor so no extra libraries are needed.
8 | Useful if you need a high number of image sizes and you'd rather not define each and every one of them with `add_image_size()`.
9 |
--------------------------------------------------------------------------------
/starter/utilities/sidebar.md:
--------------------------------------------------------------------------------
1 | # \MyApp::core()->sidebar()
2 |
3 | This utility provides tools to work with sidebars.
4 |
5 | `\MyApp::core()->sidebar()->getCurrentSidebarId( $default = 'default-sidebar', $meta_key = '_custom_sidebar' )`
6 |
7 | Return the specified default sidebar id unless a sidebar id is stored in the specified meta key for the current post/page.
8 | Useful if you wish to have per-page sidebars that you store in post meta.
9 |
--------------------------------------------------------------------------------