Laravel in WordPress Theme

Laravel is a web application framework with expressive, elegant syntax. It's one of the most popular PHP frameworks today.

Laraish brings the Laravel Framework into WordPress, which allows us to have all the benefits of Laravel. So you can create themes with less effort and more enjoyment!

Requirement
What Laraish is and is not
What's the difference between the original Laravel?
Get Started
Known Issue
- Composer race condition

Requirement

The 99% of Laraish is just the regular full stack PHP Framework Laravel. So if you have never heard of it, you're going to want to take a look at it before you can go any further.

For those who are already familiar with Laravel, it should be a piece of cake for you to get started with Laraish.

What Laraish is and is not

Laraish is not a framework for general purpose WordPress theme development.

Yes, it is a framework but not for general WordPress theme development. Laraish is aimed at helping create "homemade theme" rather than general purpose theme. So if you want to create themes with a bunch of theme options for sales or just for free distribution, you probably want to take a look at the following frameworks instead.

What's the difference between the original Laravel?

I'd say almost no differences there, except some additional tweaking, which gets Laravel to work well inside a WordPress theme. So basically you could do anything that you could do with Laravel, it's just the regular Laravel inside a WordPress theme. If you are curious about what exactly have been modified, taking a diff to the original Laravel would make sense for you.

Note: The current version of Laraish is built on Laravel 12, providing you with all the latest features, security updates, and performance improvements from the Laravel framework.

Get Started

Installation

You can install Laraish by issuing the following command via Composer.

composer create-project --prefer-dist laraish/laraish <theme-name>

Note that the MySQL server and the web server must be running before you can issue the composer create-project command to install Laraish. Because after Composer finishes the installation, it's going to run an artisan command, which requires MySQL server and the web server that host the WordPress be running at the time you issuing the command.

Also, notice that if you are on Mac and use MAMP or similar application to create your local server environment you may need to change your $PATH environment variable to make Composer use the PHP binary that MAMP provides rather than the OS's built-in PHP binary.

To ensure the asset() function operates correctly, open the .env file and insert the ASSET_URL key. Assign it the value of <THEME_PATH/public>. For instance:

ASSET_URL=/wp-content/themes/Laraish/public

Routing

Laraish replaced the original UriValidator(Illuminate\Routing\Matching\UriValidator) with its own one to allow you to specify WordPress specific routes, like "archive" or "page" or "custom post type" ex.

You define your WordPress-specific-routes in the routes/wp.php file.

For example:

use App\Http\Controllers\Wp\Home;
use App\Http\Controllers\Wp\Page;
use App\Http\Controllers\Wp\Post;
use App\Http\Controllers\Wp\NotFound;
use Laraish\Support\Facades\WpRoute;

// Regular post pages
WpRoute::post('post', [Post::class, 'index']);

// Post pages where post-type is 'movie'
WpRoute::post('movie', [Post::class, 'index']);

// The archive page of "movie" post type.
WpRoute::postArchive('movie', [Home::class, 'index']);

// The child page "works" of the "about" page.
WpRoute::page('about.works', [Page::class, 'index']);

// Any child pages of the "about" page.
WpRoute::page('about.*', [Page::class, 'index']);

// Any descendant pages of the "about" page.
WpRoute::page('about.**', [Page::class, 'index']);

// The "about" page ("about" is the slug of the page)
WpRoute::page('about', [Page::class, 'index']);

// The archive page of "foobar" term of "category" taxonomy.
WpRoute::taxonomy('category.foobar', [Home::class, 'index']);

// The archive page of "category" taxonomy.
WpRoute::taxonomy('category', [Home::class, 'index']);

// The archive page of author "jack".
WpRoute::author('jack', [Home::class, 'index']);

// The archive page for all authors.
WpRoute::author([Home::class, 'index']);

// The search result page
WpRoute::search([Home::class, 'index']);

// All pages
WpRoute::page([Page::class, 'index']);

// The home/front page.
WpRoute::home([Home::class, 'index']);

// All archive pages.
WpRoute::archive([Home::class, 'index']);

// The 404 page.
WpRoute::notFound([NotFound::class, 'index']);

Here are some notes you should keep in mind.

You can use a "dot notation" to specify the hierarchy for pages and taxonomies.
You can use the wild card to specify any child/descendant page/term of a parent/ancestor page/term.
You should care about the order of your routes. Routes that has a higher specificity should be placed more above than the routes that have a lower specificity.

Route order

The position of the route is very important.

Here is a bad example:

use App\Http\Controllers\Wp\Page;
use Laraish\Support\Facades\WpRoute;

WpRoute::page([Page::class, 'index']);
WpRoute::page('works', [Page::class, 'works']);

The problem of this code is that the second route will never get matched. Because the first route matches to any pages, so all routes after the first one will be simply ignored. That is, routes that has a higher specificity should be placed above the routes that have a lower specificity.

Auto-Discovery Routing

If you don't like to specify a route manually, you could always use the auto-discovery strategy instead. By turning on auto discovery routing, Laraish resolves the controller or view automatically the way similar to WordPress.

Use Auto-Discovery Routing in the route file.

use App\Http\Controllers\Wp\Home;
use App\Http\Controllers\Wp\Page;
use Laraish\Support\Facades\WpRoute;

WpRoute::home([Home::class, 'index']);
WpRoute::page([Page::class, 'index']);

// Fallback to auto discovery routing.
WpRoute::autoDiscovery();

Notice that you should always place auto discovery routing in the last line of your route file.

With this featured turned on, Laraish will try to find a controller or view that matches to the following naming convention.

in the <ViewRoot>/wp directory:

home.blade.php
search.blade.php
archive.blade.php
post.blade.php
post
- {$post_type}.blade.php
post-archive
- {$post_type}.blade.php
page.blade.php
page
- {$page_slug}.blade.php
- {$page_slug}
  - {$child_page}.blade.php
  - …
template
- {$template_slug}.blade.php
taxonomy.blade.php
taxonomy
- {$taxonomy}.blade.php
- {$taxonomy}
  - {$term}.blade.php
  - {$term}
    - {$child_term}.blade.php
    - …
author.blade.php
- {$nicename}.blade.php

Same rule applied to the controllers under the namespace App\Http\Controllers\Wp.

For example, If the coming request is for a page called "foo", it'll try to :

Find a controller action in the following order.
- App\Http\Controllers\Wp\Page\Foo@index.
- App\Http\Controllers\Wp\Page@index.
If no controller action found, try to find a view file in the following order (if any, pass the $post object as the view data).
- <ViewRootDir>/wp/page/foo.blade.php.
- <ViewRootDir>/wp/page.blade.php.

As you can see, the searching paths will follow the hierarchy of the queried object. In the above example queried object is the page foo. Same rule will be applied to taxonomy or post archive Etc.

If Laraish could resolve the route, it'll passes some default view data according to the type of queried object :

page
- $post
post archive
- $posts
taxonomy archive
- $term
- $posts
home
- $post if it's a "frontpage", otherwise $posts

Where $post is a Post model object, and $posts is a Laraish\Support\Wp\Query\QueryResults object contains a collection of posts.

By default, the post model will be Laraish\Support\Wp\Model\Post, but it'll try to locate a cust

Laraish

Install / Use

README