corcel下载 - corcel源码下载

模型类的集合，允许您直接从 WordPress 数据库获取数据。

Corcel 是构建在 Eloquent ORM（来自 Laravel 框架）之上的 PHP 类的集合，它提供了一个流畅的接口来连接 WordPress 数据库并直接从 WordPress 数据库获取数据。

您可以使用 WordPress 作为后端（管理面板）或 CMS，用于插入帖子、自定义类型等，以及另一端查询这些数据的任何其他 PHP 应用程序（作为模型层）。将 Corcel 与 Laravel 结合使用会更容易，但您可以自由地将它与使用 Composer 的任何 PHP 项目一起使用。

给我买杯咖啡 |在 Twitter 上关注 Corcel

安装 Corcel

版本兼容性
安装 Corcel
数据库设置
用法
- 帖子
- 高级自定义字段 (ACF) 集成
- 自定义帖子类型
- 单表继承
- 分类法
- 帖子格式
- 页数
- 类别和分类法
- 附件及修订
- 缩略图
- 选项
- 菜单
- 用户
- 验证
- 运行测试
贡献
执照

版本兼容性

拉维尔	科塞尔
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`

安装 Corcel

您需要使用 Composer 将 Corcel 安装到您的项目中：

 composer require jgrossi/corcel

配置 (Laravel)

Laravel 5.5 及更高版本

Corcel 将使用 Laravel 的自动发现来注册自己。

Laravel 5.4 及以上版本

您必须在config/app.php中包含CorcelServiceProvider ：

 ' providers ' => [
    /*
     * Package Service Providers...
     */
    Corcel  Laravel CorcelServiceProvider::class,
]

发布配置文件

现在配置我们的配置文件，以确保您的数据库设置正确，并允许您以非常简单的方式注册自定义帖子类型和短代码：

在终端中运行以下 Artisan 命令：

 php artisan vendor:publish --provider="CorcelLaravelCorcelServiceProvider"

现在您有一个config/corcel.php配置文件，您可以在其中设置与 WordPress 表的数据库连接等。

数据库设置

Laravel 设置

只需在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 ' ,

其他 PHP 框架（非 Laravel）设置

在这里，您必须配置数据库以满足 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

按自定义字段查询帖子（Meta）

通过使用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)

如果您想检索由高级自定义字段 (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 类，就会返回该对象而不是默认对象。

简码

来自配置（Laravel）

您可以在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

如果您使用 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;
    }

不使用 Laravel

您可以使用AuthUserProvider类来手动验证用户：

 $ userProvider = new Corcel  Laravel  Auth  AuthUserProvider ;
$ user = $ userProvider -> retrieveByCredentials ([ ' username ' => ' admin ' ]);
if (! is_null ( $ user ) && $ userProvider -> validateCredentials ( $ user , [ ' password ' => ' admin ' ])) {
    // successfully login
}

请记住，您可以使用username和email作为用户的凭据。

运行测试

要运行 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 ；
等待批准:-)

执照

展开