Download the PHP package vinhnguyen/corcel without Composer
On this page you can find all versions of the php package vinhnguyen/corcel. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download vinhnguyen/corcel
More information about vinhnguyen/corcel
Files in vinhnguyen/corcel
Package corcel
Short Description Use WordPress backend with Laravel or any PHP framework
License MIT
Homepage http://github.com/corcel/corcel
Informations about the package corcel
A collection of Model classes that allows you to get data directly from a WordPress database.
Corcel is a collection of PHP classes built on top of Eloquent ORM (from Laravel framework), that provides a fluent interface to connect and get data directly from a WordPress database.
You can use WordPress as the backend (administration panel) or CMS, for inserting posts, custom types, etc, and any other PHP app in the other side querying those data (as a Model layer). It's easier to use Corcel with Laravel, but you're free to use it with any PHP project that uses Composer.
Buy me a Coffee | Follow Corcel on Twitter
Table of Contents
Installing Corcel
- Version Compatibility
- Installing Corcel
- Database Setup
- Usage
- Posts
- Advanced Custom Fields (ACF) Integration
- Custom Post Type
- Single Table Inheritance
- Taxonomies
- Post Format
- Pages
- Categories & Taxonomies
- Attachments & Revision
- Thumbnails
- Options
- Menu
- Users
- Authentication
- Running Tests
- Contributing
- License
Version Compatibility
Laravel | Corcel |
---|---|
5.1.x | 2.1.x |
5.2.x | 2.2.x |
5.3.x | 2.3.x |
5.4.x | 2.4.x |
5.5.x | 2.5.x |
5.6.x | 2.6.x |
5.7.x | 2.7.x |
Installing Corcel
You need to use Composer to install Corcel into your project:
Configuring (Laravel)
Now you have to include CorcelServiceProvider
in your config/app.php
:
Now configure our config file to make sure your database is set correctly and to allow you to register custom post types and shortcodes in a very easy way:
Run the following Artisan command in your terminal:
Now you have a config/corcel.php
config file, where you can set the database connection with WordPress tables and much more.
Database Setup
Laravel Setup
Just set the database connection
you want to be used by Corcel in config/corcel.php
.
Let' suppose you have those following database connections in your config/database.php
file:
In this case you should want to use the wordpress
connection for Corcel, so just set it into the Corcel config file config/corcel.php
:
Other PHP Framework (not Laravel) Setup
Here you have to configure the database to fit the Corcel requirements. First, you should include the Composer autoload
file if not already loaded:
Now you must set your WordPress database params:
You can specify all Eloquent params, but some are default (but you can override them).
Usage
Posts
Every time you see
Post::method()
, if you're using your own Post class (where you set the connection name), likeApp\Post
you should useApp\Post::method()
and notPost::method()
. All the examples are assuming you already know this difference.In the examples, every time you see
Post::method()
assumeCorcel\Model\Post::method()
.
Creating your own model classes
Optionally you can create your own Post
model (or Page, or whatever) which extends Corcel\Post
. Then set the connection name (if you want to override the Corcel's default one) you're using, in this case foo-bar
:
Extending
Corcel\Model\Post
class can add flexibility to your project, once you can add custom methods and logic, according what you need to use from your WordPress database.
So, now you can fetch WP database data using your own class:
Just remember you don't have to extends our
Post
class, you can useCorcel\Model\Post
and all others model without any problem.
Meta Data (Custom Fields)
NOTE: In Corcel v1 you could save meta data using the
Post::save()
method. That's not allowed anymore. UsesaveMeta()
orcreateMeta()
(see below) methods to save post meta.
You can retrieve meta data from posts too.
To create or update meta data form a User just use the saveMeta()
or saveField()
methods. They return bool
like the Eloquent save()
method.
You can save many meta data at the same time too:
You also have the createMeta()
and createField()
methods, that work like the saveX()
methods, but they are used only for creation and return the PostMeta
created instance, instead of bool
.
Querying Posts by Custom Fields (Meta)
There are multiples possibilities to query posts by their custom fields (meta) by using scopes on a Post
(or another other model which uses the HasMetaFields
trait) class:
To check if a meta key exists, use the hasMeta()
scope:
If you want to precisely match a meta-field, you can use the hasMeta()
scope with a value.
If you need to match multiple meta-fields, you can also use the hasMeta()
scope passing an array as parameter:
If you need to match a case-insensitive string, or match with wildcards, you can use the hasMetaLike()
scope with a value. This uses an SQL LIKE
operator, so use '%' as a wildcard operator.
Fields Aliases
The Post
class has support to "aliases", so if you check the Post
class you should note some aliases defined in the static $aliases
array, like title
for post_title
and content
for post_content
.
If you're extending the Post
class to create your own class you can use $aliases
too. Just add new aliases to that static property inside your own class and it will automatically inherit all aliases from parent Post
class:
Custom Scopes
To order posts you can use newest()
and oldest()
scopes, for both Post
and User
classes:
Pagination
To order posts just use Eloquent paginate()
method:
To display the pagination links just call the links()
method:
Advanced Custom Fields (ACF)
If you want to retrieve a custom field created by the Advanced Custom Fields (ACF) plugin, you have to install the corcel/acf
plugin - click here for more information - and call the custom field like this:
To avoid unnecessary SQL queries just set the field type you're requesting. Usually two SQL queries are necessary to get the field type, so if you want to specify it you're skipping those extra queries:
Custom Post Type
You can work with custom post types too. You can use the type(string)
method or create your own class.
Using type()
method will make Corcel to return all objects as Corcel\Post
. Using your custom class you have the advantage to customize classes, including custom methods and properties, return all objects as Video
, for example.
Custom post types and meta data:
Configuring the returning Instance
Every time you call something like Post::type('video)->first()
or Video::first()
you receive a Corcel\Model\Post
instance.
If you choose to create a new class for your custom post type, you can have this class be returned for all instances of that post type.
Registering Post Types (the easy way)
Instead of call Post::registerPostType()
method for all custom post type you want to register, just use the Corcel's config file and map all custom posts and it's classes. They will be registered automatically for you:
So every time you query a custom post type the mapped instance will be returned.
This is particular useful when you are intending to get a Collection of Posts of different types (e.g. when fetching the posts defined in a menu).
Registering Post Types (the hard way)
You can also do this for inbuilt classes, such as Page or Post. Simply register the Page or Post class with the associated post type string, and that object will be returned instead of the default one.
Shortcodes
From config (Laravel)
You can map all shortcodes you want inside the config/corcel.php
file, under the 'shortcodes'
key. In this case you should create your own class that implements
the Corcel\Shortcode
interface, that requires a render()
method:
This is a sample shortcode class:
In runtime
You can add shortcodes by calling the addShortcode
method on the Post
model :
Laravel 5.5 uses Package Auto-Discovery, so doesn't require you to manually add the ServiceProvider
If you are using Laravel, we suggest adding your shortcodes handlers in App\Providers\AppServiceProvider
, in the boot
method.
Shortcode Parsing
Shortcodes are parsed with the thunderer/shortcode library.
Several different parsers are provided. RegularParser
is the most technically correct and is provided by default. This is suitable for most cases. However if you encounter some irregularities in your shortcode parsing, you may need to configure Corcel to use the WordpressParser
, which more faithfully matches WordPress' shortcode regex. To do this, if you are using Laravel, edit the config/corcel.php
file, and uncomment your preferred parser. Alternatively, you can replace this with a parser of your own.
If you are not using Laravel, you can to do this in runtime, calling the setShortcodeParser()
method from any class which uses the Shortcodes
trait, such as Post
, for example.
For more information about the shortcode package, click here.
Taxonomies
You can get taxonomies for a specific post like:
Or you can search for posts using its taxonomies:
Post Format
You can also get the post format, like the WordPress function get_post_format()
:
Pages
Pages are like custom post types. You can use Post::type('page')
or the Corcel\Model\Page
class.
Categories and Taxonomies
Get a category or taxonomy or load posts from a certain category. There are multiple ways to achieve it.
Attachment and Revision
Getting the attachment and/or revision from a Post
or Page
.
Thumbnails
Getting the thumbnail for a Post
or Page
.
To retrieve a particular thumbnail size you may call the ->size()
method on the thumbnail object and pass in a thumbnail size string parameter (e.g. thumbnail
or medium
). If the thumbnail has been generated, this method returns an array of image metadata, otherwise the original image URL will be returned as a fallback.
Options
In previous versions of Corcel this classe was called
Options
instead ofOption
(singular). So take care of using always this class in the singular form starting fromv2.0.0
.The
Option::getAll()
method was removed in Corcel 2+, in favor ofOption::asArray($keys [])
.
You can use the Option
class to get data from wp_options
table:
You can also add new options:
You can get all options in a simple array:
Or you can specify only the keys you want to get:
Menu
To get a menu by its slug, use the syntax below. The menu items will be loaded in the items
variable (it's a collection of Corcel\Model\MenuItem
objects).
The currently supported menu items are: Pages, Posts, Custom Links and Categories.
Once you'll have instances of MenuItem
class, if you want to use the original instance (like the original Page or Term, for example), just call the MenuItem::instance()
method. The MenuItem
object is just a post with post_type
equals nav_menu_item
:
The instance()
method will return the matching object:
Post
instance forpost
menu item;Page
instance forpage
menu item;CustomLink
instance forcustom
menu item;Term
instance forcategory
menu item.
Multi-levels Menus
To handle multi-levels menus, loop through all the menu items to put them on the right levels, for example.
You can use the MenuItem::parent()
method to retrieve the parent instance of that menu item:
To group menu items according their parents, you can use the ->groupBy()
method in the $menu->items
collection, grouping menu items by their $item->parent()->ID
.
To read more about the groupBy()
method take a look on the Laravel documentation.
Users
You can manipulate users in the same manner you work with posts:
Authentication
Using Laravel
Make sure you have CorcelServiceProvider
provider registered in config/app.php
:
And then, define the user provider in config/auth.php
to allow Laravel to login with WordPress users:
Now you can use the Auth
facade to authenticate users:
To make Laravel's Password Reset work with Corcel, we have to override how passwords are stored in the database. To do this, you must change Auth/PasswordController.php
from:
to
Not using Laravel
You can use the AuthUserProvider
class to manually authenticate a user :
Remember you can use both
username
and
Running Tests
To run the phpunit tests, execute the following command :
If you have the global phpunit
command installed you can just type:
All tests were written using Sqlite with :memory
database, so it runs in your memory. All tests use factories
and migrations
. Take a look on tests/database/factories
and tests/database/migrations
directories for more information.
Contributing
All contributions are welcome to help improve Corcel.
Before you submit your Pull Request (PR) consider the following guidelines:
-
Fork https://github.com/corcel/corcel in Github;
-
Clone your forked repository (not Corcel's) locally and create your own branch based on the version you want to fix (
2.1
,2.2
,2.3
,2.4
or2.5
):git checkout -b my-fix-branch 2.5
; -
Make all code changes. Remember here to write at least one test case for any feature you add or any bugfix (if it's not tested yet). Our goal is to have 100% of the code covered by tests, so help us to write a better code ;-) If you don' have experience with tests it's a good opportunity to learn. Just take a look into our tests cases and you'll see how simple they are.
-
Run the unit tests locally to make sure your changes did not break any other piece of code;
-
Push your new branch to your forked repository, usually
git push origin HEAD
should work; -
In GitHub again, create a Pull Request (PR) from your custom
my-fix-branch
branch (from your forked repository) to the related branch (corcel:2.5
, for example, notcorcel:master
, please; - Wait for the approval :-)
Licence
MIT License © Junior Grossi
All versions of corcel with dependencies
illuminate/database Version 5.8.*
illuminate/filesystem Version 5.8.*
illuminate/support Version 5.8.*
fzaninotto/faker Version ^1.6
hautelook/phpass Version 0.3.*
thunderer/shortcode Version ^0.6.2