模型類別的集合,可讓您直接從 WordPress 資料庫取得資料。
Corcel 是建立在 Eloquent ORM(來自 Laravel 框架)之上的 PHP 類別的集合,它提供了一個流暢的介面來連接 WordPress 資料庫並直接從 WordPress 資料庫取得資料。
您可以使用 WordPress 作為後端(管理面板)或 CMS,用於插入文章、自訂類型等,以及另一端查詢這些資料的任何其他 PHP 應用程式(作為模型層)。將 Corcel 與 Laravel 結合使用會更容易,但您可以自由地將它與使用 Composer 的任何 PHP 專案一起使用。
買杯咖啡給我 |在 Twitter 上關注 Corcel
拉維爾 | 科塞爾 |
---|---|
5.1.x | ~2.1.0 |
5.2.x | ~2.2.0 |
5.3.x | ~2.3.0 |
5.4.x | ~2.4.0 |
5.5.x | ~2.5.0 |
5.6.x | ~2.6.0 |
5.7.x | ~2.7.0 |
5.8.x | ~2.8.0 |
6.0.x | ^3.0.0 |
7.0.x | ^4.0.0 |
8.0.x | ^5.0.0 |
9.0.x | ^6.0.0 |
10.0.x | ^7.0.0 |
11.0.x | ^8.0.0 |
您需要使用 Composer 將 Corcel 安裝到您的專案中:
composer require jgrossi/corcel
Corcel 將使用 Laravel 的自動發現來註冊自己。
您必須在config/app.php
中包含CorcelServiceProvider
:
' providers ' => [
/*
* Package Service Providers...
*/
Corcel Laravel CorcelServiceProvider::class,
]
現在配置我們的配置文件,以確保您的資料庫設定正確,並允許您以非常簡單的方式註冊自訂帖子類型和短代碼:
在終端機中執行以下 Artisan 命令:
php artisan vendor:publish --provider="CorcelLaravelCorcelServiceProvider"
現在您有一個config/corcel.php
設定文件,您可以在其中設定與 WordPress 表的資料庫連接等。
只需在config/corcel.php
中設定 Corcel 使用的資料庫connection
即可。
假設您的config/database.php
檔案中有以下資料庫連線:
// File: /config/database.php
' connections ' => [
' mysql ' => [ // for Laravel database
' driver ' => ' mysql ' ,
' host ' => ' localhost ' ,
' database ' => ' mydatabase ' ,
' username ' => ' admin '
'password' => 'secret',
' charset ' => ' utf8 ' ,
' collation ' => ' utf8_unicode_ci ' ,
' prefix ' => '' ,
' strict ' => false ,
' engine ' => null ,
],
' wordpress ' => [ // for WordPress database (used by Corcel)
' driver ' => ' mysql ' ,
' host ' => ' localhost ' ,
' database ' => ' mydatabase ' ,
' username ' => ' admin ' ,
' password ' => ' secret ' ,
' charset ' => ' utf8 ' ,
' collation ' => ' utf8_unicode_ci ' ,
' prefix ' => ' wp_ ' ,
' strict ' => false ,
' engine ' => null ,
],
],
在這種情況下,您應該希望使用 Corcel 的wordpress
連接,因此只需將其設定到 Corcel 設定檔config/corcel.php
中:
' connection ' => ' wordpress ' ,
在這裡,您必須配置資料庫以滿足 Corcel 要求。首先,如果尚未加載,您應該包含 Composer autoload
檔案:
require __DIR__ . ' /vendor/autoload.php ' ;
現在您必須設定 WordPress 資料庫參數:
$ params = [
' database ' => ' database_name ' ,
' username ' => ' username ' ,
' password ' => ' pa$$word ' ,
' prefix ' => ' wp_ ' // default prefix is 'wp_', you can change to your own prefix
];
Corcel Database:: connect ( $ params );
您可以指定所有 Eloquent 參數,但有些參數是預設的(但您可以覆寫它們)。
' driver ' => ' mysql ' ,
' host ' => ' localhost ' ,
' charset ' => ' utf8 ' ,
' collation ' => ' utf8_unicode_ci ' ,
' prefix ' => ' wp_ ' , // Specify the prefix for WordPress tables, default prefix is 'wp_'
每次看到
Post::method()
時,如果您使用自己的 Post 類別(在其中設定連接名稱),例如AppPost
您應該使用AppPost::method()
而不是Post::method()
。所有範例都假設您已經知道這種差異。
在範例中,每次看到
Post::method()
時都會假設CorcelModelPost::method()
。
// All published posts
$ posts = Post:: published ()-> get ();
$ posts = Post:: status ( ' publish ' )-> get ();
// A specific post
$ post = Post:: find ( 31 );
echo $ post -> post_title ;
您可以選擇建立自己的Post
模型(或 Page 或其他)來擴充CorcelPost
。然後設定您正在使用的連線名稱(如果您想要覆寫 Corcel 的預設名稱),在本例中foo-bar
:
一旦您可以根據需要使用 WordPress 資料庫中的內容添加自訂方法和邏輯,擴展
CorcelModelPost
類別可以為您的專案增加靈活性。
<?php // File: app/Post.php
namespace App ;
use Corcel Model Post as Corcel ;
class Post extends Corcel
{
protected $ connection = ' foo-bar ' ;
public function customMethod () {
//
}
}
因此,現在您可以使用自己的類別來獲取 WP 資料庫資料:
$ posts = App Post:: all (); // using the 'foo-bar' connection
請記住,您不必擴展我們的
Post
類,您可以毫無問題地使用CorcelModelPost
和所有其他模型。
注意:在 Corcel v1 中,您可以使用
Post::save()
方法儲存元資料。不再允許這樣了。使用saveMeta()
或createMeta()
(見下文)方法來儲存貼文元。
您也可以從帖子中檢索元資料。
// Get a custom meta value (like 'link' or whatever) from a post (any type)
$ post = Post:: find ( 31 );
echo $ post -> meta -> link ; // OR
echo $ post -> fields -> link ;
echo $ post -> link ; // OR
要建立或更新使用者的元數據,只需使用saveMeta()
或saveField()
方法。它們像 Eloquent save()
方法一樣傳回bool
。
$ post = Post:: find ( 1 );
$ post -> saveMeta ( ' username ' , ' jgrossi ' );
您也可以同時儲存許多元資料:
$ post = Post:: find ( 1 );
$ post -> saveMeta ([
' username ' => ' jgrossi ' ,
' url ' => ' http://jgrossi.com ' ,
]);
您也擁有createMeta()
和createField()
方法,其運作方式與saveX()
方法類似,但它們僅用於建立並傳回PostMeta
所建立的實例,而不是bool
。
$ post = Post:: find ( 1 );
$ postMeta = $ post -> createMeta ( ' foo ' , ' bar ' ); // instance of PostMeta class
$ trueOrFalse = $ post -> saveMeta ( ' foo ' , ' baz ' ); // boolean
透過使用Post
(或使用HasMetaFields
特徵的其他模型)類別上的範圍,可以透過自訂欄位(元)查詢貼文的多種可能性:
若要檢查元鍵是否存在,請使用hasMeta()
作用域:
// Finds a published post with a meta flag.
$post = Post::published()->hasMeta('featured_article')->first();
如果您想要精確匹配元字段,可以將hasMeta()
範圍與值一起使用。
// Find a published post which matches both meta_key and meta_value.
$ post = Post:: published ()-> hasMeta ( ' username ' , ' jgrossi ' )-> first ();
如果需要符合多個元字段,也可以使用hasMeta()
作用域傳遞數組作為參數:
$ post = Post:: hasMeta ([ ' username ' => ' jgrossi ' ])-> first ();
$ post = Post:: hasMeta ([ ' username ' => ' jgrossi ' , ' url ' => ' jgrossi.com ' ])-> first ();
// Or just passing the keys
$ post = Post:: hasMeta ([ ' username ' , ' url ' ])-> first ();
如果需要匹配不區分大小寫的字串,或與通配符匹配,可以將hasMetaLike()
範圍與值一起使用。這使用 SQL LIKE
運算符,因此使用“%”作為通配符運算符。
// Will match: 'J Grossi', 'J GROSSI', and 'j grossi'.
$ post = Post:: published ()-> hasMetaLike ( ' author ' , ' J GROSSI ' )-> first ();
// Using % as a wildcard will match: 'J Grossi', 'J GROSSI', 'j grossi', 'Junior Grossi' etc.
$ post = Post:: published ()-> hasMetaLike ( ' author ' , ' J%GROSSI ' )-> first ();
Post
類別支援“別名”,因此如果您檢查Post
類,您應該注意靜態$aliases
數組中定義的一些別名,例如post_title
的title
和post_content
的content
。
$ post = Post:: find ( 1 );
$ post -> title === $ post -> post_title ; // true
如果您要擴充Post
類別來建立自己的類別,您也可以使用$aliases
。只需將新別名新增到您自己的類別中的靜態屬性中,它將自動繼承父Post
類別的所有別名:
class A extends Corcel Post
{
protected static $ aliases = [
' foo ' => ' post_foo ' ,
];
}
$ a = A:: find ( 1 );
echo $ a -> foo ;
echo $ a -> title ; // from Post class
若要對貼文進行排序,您可以對Post
和User
類別使用newest()
和oldest()
範圍:
$ newest = Post:: newest ()-> first ();
$ oldest = Post:: oldest ()-> first ();
要對帖子進行排序,只需使用 Eloquent paginate()
方法:
$ posts = Post:: published ()-> paginate ( 5 );
foreach ( $ posts as $ post ) {
// ...
}
要顯示分頁鏈接,只需呼叫links()
方法:
{{ $ posts -> links () }}
如果您想檢索由高級自訂字段 (ACF) 插件建立的自訂字段,您必須安裝corcel/acf
插件 - 按一下此處以了解更多資訊 - 並像這樣調用自訂欄位:
$ post = Post:: find ( 123 );
echo $ post -> acf -> some_radio_field ;
$ repeaterFields = $ post -> acf -> my_repeater_name ;
為了避免不必要的 SQL 查詢,只需設定您要求的欄位類型。通常需要兩個 SQL 查詢來取得欄位類型,因此如果您想指定它,您將跳過這些額外的查詢:
$ post = Post:: find ( 123 );
echo $ post -> acf -> text ( ' text_field_name ' );
echo $ post -> acf -> boolean ( ' boolean_field_name ' );
您也可以使用自訂貼文類型。您可以使用type(string)
方法或建立自己的類別。
// using type() method
$ videos = Post:: type ( ' video ' )-> status ( ' publish ' )-> get ();
// using your own class
class Video extends Corcel Post
{
protected $ postType = ' video ' ;
}
$ videos = Video:: status ( ' publish ' )-> get ();
使用type()
方法將使 Corcel 以CorcelPost
形式傳回所有物件。使用自訂類,您可以自訂類,包括自訂方法和屬性,例如將所有物件傳回為Video
。
自訂貼文類型和元資料:
// Get 3 posts with custom post type (store) and show its address
$ stores = Post:: type ( ' store ' )-> status ( ' publish ' )-> take ( 3 )-> get ();
foreach ( $ stores as $ store ) {
$ storeAddress = $ store -> address ; // option 1
$ storeAddress = $ store -> meta -> address ; // option 2
$ storeAddress = $ store -> fields -> address ; // option 3
}
每次您呼叫Post::type('video)->first()
或Video::first()
之類的內容時,您都會收到一個CorcelModelPost
實例。
如果您選擇為自訂貼文類型建立新類,則可以為該貼文類型的所有執行個體傳回該類別。
無需為要註冊的所有自訂貼文類型呼叫Post::registerPostType()
方法,只需使用 Corcel 的設定檔並映射所有自訂貼文及其類別即可。他們將自動為您註冊:
' post_types ' => [
' video ' => App Video::class,
' foo ' => App Foo::class,
]
因此,每次查詢自訂貼文類型時,都會傳回已對應的實例。
當您打算取得不同類型的貼文集合時(例如,在取得選單中定義的貼文時),這特別有用。
//all objects in the $videos Collection will be instances of Post
$ videos = Post:: type ( ' video ' )-> status ( ' publish ' )-> get ();
// register the video custom post type and its particular class
Post:: registerPostType ( ' video ' , ' AppVideo ' )
//now all objects in the $videos Collection will be instances of Video
$ videos = Post:: type ( ' video ' )-> status ( ' publish ' )-> get ();
您也可以對內建類別(例如 Page 或 Post)執行此操作。只需使用關聯的貼文類型字串註冊 Page 或 Post 類,就會傳回該物件而不是預設物件。
您可以在config/corcel.php
檔案中的'shortcodes'
鍵下對應您想要的所有短代碼。在這種情況下,您應該創建自己的類別來implements
CorcelShortcode
接口,該接口需要render()
方法:
' shortcodes ' => [
' foo ' => App Shortcodes FooShortcode::class,
' bar ' => App Shortcodes BarShortcode::class,
],
這是一個範例短代碼類別:
class FakeShortcode implements Corcel Shortcode
{
/**
* @param ShortcodeInterface $shortcode
* @return string
*/
public function render ( ShortcodeInterface $ shortcode )
{
return sprintf (
' html-for-shortcode-%s-%s ' ,
$ shortcode -> getName (),
$ shortcode -> getParameter ( ' one ' )
);
}
}
您可以透過呼叫Post
模型上的addShortcode
方法來新增短程式碼:
// [gallery id="1"]
Post:: addShortcode ( ' gallery ' , function ( $ shortcode ) {
return $ shortcode -> getName () . ' . ' . $ shortcode -> getParameter ( ' id ' );
});
$ post = Post:: find ( 1 );
echo $ post -> content ;
Laravel 5.5 使用 Package Auto-Discovery,因此不需要您手動新增 ServiceProvider
如果您使用 Laravel,我們建議在boot
方法中的AppProvidersAppServiceProvider
中新增您的短代碼處理程序。
短代碼使用Thunderer/shortcode庫進行解析。
提供了幾種不同的解析器。 RegularParser
在技術上是最正確的,並且是預設提供的。這適用於大多數情況。但是,如果您在短程式碼解析中遇到一些異常情況,則可能需要設定 Corcel 以使用WordpressParser
,它更忠實地符合 WordPress 的短程式碼正規表示式。為此,如果您使用 Laravel,請編輯config/corcel.php
文件,並取消註解您的首選解析器。或者,您可以用您自己的解析器替換它。
' shortcode_parser ' => Thunder Shortcode Parser RegularParser::class,
// 'shortcode_parser' => ThunderShortcodeParserWordpressParser::class,
如果您不使用 Laravel,則可以在執行時間執行此操作,從任何使用Shortcodes
特徵的類別(例如Post
)呼叫setShortcodeParser()
方法。
$ post -> setShortcodeParser ( new WordpressParser ());
echo $ post -> content ; // content parsed with "WordpressParser" class
有關短代碼包的更多信息,請按此處。
您可以獲得特定帖子的分類法,例如:
$ post = Post:: find ( 1 );
$ taxonomy = $ post -> taxonomies ()-> first ();
echo $ taxonomy -> taxonomy ;
或者您可以使用其分類法搜尋帖子:
$ post = Post:: taxonomy ( ' category ' , ' php ' )-> first ();
您也可以取得貼文格式,例如 WordPress 函式get_post_format()
:
echo $ post -> getFormat (); // should return something like 'video', etc
頁面就像自訂帖子類型。您可以使用Post::type('page')
或CorcelModelPage
類別。
use Corcel Model Page ;
// Find a page by slug
$ page = Page:: slug ( ' about ' )-> first (); // OR
$ page = Post:: type ( ' page ' )-> slug ( ' about ' )-> first ();
echo $ page -> post_title ;
取得類別或分類法或載入特定類別的貼文。有多種方法可以實現它。
// all categories
$ cat = Taxonomy:: category ()-> slug ( ' uncategorized ' )-> posts -> first ();
echo " <pre> " ; print_r ( $ cat -> name ); echo " </pre> " ;
// only all categories and posts connected with it
$ cat = Taxonomy:: where ( ' taxonomy ' , ' category ' )-> with ( ' posts ' )-> get ();
$ cat -> each ( function ( $ category ) {
echo $ category -> name ;
});
// clean and simple all posts from a category
$ cat = Category:: slug ( ' uncategorized ' )-> posts -> first ();
$ cat -> posts -> each ( function ( $ post ) {
echo $ post -> post_title ;
});
從Post
或Page
取得附件和/或修訂。
$ page = Page:: slug ( ' about ' )-> with ( ' attachment ' )-> first ();
// get feature image from page or post
print_r ( $ page -> attachment );
$ post = Post:: slug ( ' test ' )-> with ( ' revision ' )-> first ();
// get all revisions from a post or page
print_r ( $ post -> revision );
取得Post
或Page
的縮圖。
$ post = Post:: find ( 1 );
// Retrieve an instance of CorcelModelMetaThumbnailMeta.
print_r ( $ post -> thumbnail );
// For convenience you may also echo the thumbnail instance to get the URL of the original image.
echo $ post -> thumbnail ;
若要檢索特定的縮圖大小,您可以在縮圖物件上呼叫->size()
方法並傳入縮圖大小字串參數(例如thumbnail
或medium
)。如果縮圖已生成,此方法將傳回圖像元資料數組,否則將返回原始圖像 URL 作為後備。
if ( $ post -> thumbnail !== null ) {
/**
* [
* 'file' => 'filename-300x300.jpg',
* 'width' => 300,
* 'height' => 300,
* 'mime-type' => 'image/jpeg',
* 'url' => 'http://localhost/wp-content/uploads/filename-300x300.jpg',
* ]
*/
print_r ( $ post -> thumbnail -> size ( Corcel Model Meta ThumbnailMeta:: SIZE_THUMBNAIL ));
// http://localhost/wp-content/uploads/filename.jpg
print_r ( $ post -> thumbnail -> size ( ' invalid_size ' ));
}
在 Corcel 的早期版本中,此類稱為
Options
而不是Option
(單數)。因此,從v2.0.0
開始,請務必以單數形式使用此類。
Corcel 2+ 中刪除了
Option::getAll()
方法,取而代之的是Option::asArray($keys [])
。
您可以使用Option
類別從wp_options
表取得資料:
$ siteUrl = Option:: get ( ' siteurl ' );
您也可以新增選項:
Option:: add ( ' foo ' , ' bar ' ); // stored as string
Option:: add ( ' baz ' , [ ' one ' => ' two ' ]); // this will be serialized and saved
您可以在一個簡單的陣列中取得所有選項:
$ options = Option:: asArray ();
echo $ options [ ' siteurl ' ];
或者您可以僅指定您想要取得的金鑰:
$ options = Option:: asArray ([ ' siteurl ' , ' home ' , ' blogname ' ]);
echo $ options [ ' home ' ];
要透過其 slug 取得選單,請使用以下語法。選單項目將會載入到items
變數中(它是CorcelModelMenuItem
物件的集合)。
目前支援的選單項目有:頁面、貼文、自訂連結和類別。
一旦您擁有了MenuItem
類別的實例,如果您想使用原始實例(例如原始 Page 或 Term),只需呼叫MenuItem::instance()
方法即可。 MenuItem
物件只是一個post_type
等於nav_menu_item
的貼文:
$ menu = Menu:: slug ( ' primary ' )-> first ();
foreach ( $ menu -> items as $ item ) {
echo $ item -> instance ()-> title ; // if it's a Post
echo $ item -> instance ()-> name ; // if it's a Term
echo $ item -> instance ()-> link_text ; // if it's a custom link
}
instance()
方法將傳回符合的物件:
post
選單項目的Post
實例;page
選單項目的Page
實例;custom
選單項目的CustomLink
實例;category
選單項目的Term
實例。例如,要處理多層選單,請循環遍歷所有選單項目以將它們放在正確的層級上。
您可以使用MenuItem::parent()
方法來擷取該選單項目的父實例:
$ items = Menu:: slug ( ' foo ' )-> first ()-> items ;
$ parent = $ items -> first ()-> parent (); // Post, Page, CustomLink or Term (category)
若要根據選單項目的父級將選單項目分組,可以使用$menu->items
集合中的->groupBy()
方法,按$item->parent()->ID
將選單項目分組。
要了解有關groupBy()
方法的更多信息,請查看 Laravel 文件。
您可以像處理帖子一樣操作用戶:
// All users
$ users = User:: get ();
// A specific user
$ user = User:: find ( 1 );
echo $ user -> user_login ;
如果您使用 Laravel 5.4 或更早版本,請確保您已註冊CorcelServiceProvider
提供者。
然後,在config/auth.php
中定義使用者提供者以允許 Laravel 使用 WordPress 使用者登入:
' providers ' => [
' users ' => [
' driver ' => ' corcel ' ,
' model ' => Corcel Model User::class,
],
],
現在您可以使用Auth
外觀來驗證使用者身分:
Auth:: validate ([
' email ' => ' [email protected] ' , // or using 'username' too
' password ' => ' secret ' ,
]);
為了讓 Laravel 的密碼重置與 Corcel 配合使用,我們必須重寫密碼在資料庫中的儲存方式。為此,您必須將Auth/PasswordController.php
變更為:
use App Http Controllers Controller ;
use Illuminate Foundation Auth ResetsPasswords ;
class PasswordController extends Controller
{
use ResetsPasswords;
到
use App Http Controllers Controller ;
use Illuminate Foundation Auth ResetsPasswords ;
use Corcel Laravel Auth ResetsPasswords as CorcelResetsPasswords ;
class PasswordController extends Controller
{
use ResetsPasswords, CorcelResetsPasswords {
CorcelResetsPasswords::resetPassword insteadof ResetsPasswords;
}
您可以使用AuthUserProvider
類別來手動驗證使用者:
$ userProvider = new Corcel Laravel Auth AuthUserProvider ;
$ user = $ userProvider -> retrieveByCredentials ([ ' username ' => ' admin ' ]);
if (! is_null ( $ user ) && $ userProvider -> validateCredentials ( $ user , [ ' password ' => ' admin ' ])) {
// successfully login
}
請記住,您可以使用
username
和
若要執行 phpunit 測試,請執行下列命令:
./vendor/bin/phpunit
如果您安裝了全域phpunit
命令,您只需鍵入:
phpunit
所有測試都是使用帶有:memory
資料庫的 Sqlite 編寫的,因此它在您的記憶體中運行。所有測試都使用factories
和migrations
。查看tests/database/factories
和tests/database/migrations
目錄以獲取更多資訊。
歡迎所有貢獻來幫助改進 Corcel。
在提交 Pull Request (PR) 之前,請考慮以下準則:
在 Github 中分叉 https://github.com/corcel/corcel;
在本地複製您的分叉儲存庫(不是 Corcel 的),並根據要修復的版本( 2.1
、 2.2
、 2.3
、 2.4
或2.5
)建立您自己的分支: git checkout -b my-fix-branch 2.5
;
更改所有程式碼。請記住在這裡為您添加的任何功能或任何錯誤修復至少編寫一個測試案例(如果尚未測試)。我們的目標是讓測試覆蓋 100% 的程式碼,因此幫助我們編寫更好的程式碼;-) 如果您沒有測試經驗,那麼這是一個很好的學習機會。只需查看我們的測試案例,您就會發現它們是多麼簡單。
在本地運行單元測試,以確保您的更改不會破壞任何其他程式碼;
將新分支推送到分叉存儲庫,通常git push origin HEAD
應該可以工作;
再次在 GitHub 中,從您的自訂my-fix-branch
分支(從您的分叉儲存庫)建立拉取要求 (PR) 到相關分支(例如corcel:2.5
,而不是corcel:master
;
等待批准:-)
麻省理工學院許可證 © Junior Grossi