README

用于管理officialtexts的包。

步骤 1: 设置包

A) 下载并安装N1c0Officialtext

要安装N1c0Officialtext，请运行以下命令

$ php composer.phar require n1c01a5/n1c0officialtext-bundle

B) 启用包

在kernel中启用所需的包

<?php
// app/AppKernel.php

public function registerBundles()
{
    $bundles = array(
        // ...
        new FOS\RestBundle\FOSRestBundle(),
        new JMS\SerializerBundle\JMSSerializerBundle(),
        new Nelmio\ApiDocBundle\NelmioApiDocBundle(),
        new Bazinga\Bundle\HateoasBundle\BazingaHateoasBundle(),
        new Stof\DoctrineExtensionsBundle\StofDoctrineExtensionsBundle(),
        new N1c0\OfficialtextBundle\N1c0OfficialtextBundle(),
    );
}

FOSRestBundle, StofDoctrineExtensionsBundle和NelmioApiDocBundle必须配置。此包需要PHP的Diff实现："sebastian/diff": "*" (composer.json).

C) 启用Http Method Override

如此处所述启用HTTP Method覆盖

从symfony 2.3开始，您只需修改您的config.yml

# app/config/config.yml

framework:
    http_method_override: true

步骤 2: 设置Doctrine ORM映射

ORM实现不提供具体的Officialtext类供您使用，您必须创建一个。这可以通过扩展包提供的抽象实体并创建适当的映射来完成。

例如，officialtext实体

<?php
// src/MyProject/MyBundle/Entity/Officialtext.php

namespace MyProject\MyBundle\Entity;

use Doctrine\ORM\Mapping as ORM;
use N1c0\OfficialtextBundle\Entity\Officialtext as BaseOfficialtext;

/**
 * @ORM\Entity
 * @ORM\ChangeTrackingPolicy("DEFERRED_EXPLICIT")
 */
class Officialtext extends BaseOfficialtext
{
    /**
     * @ORM\Id
     * @ORM\Column(type="guid", length=36)
     * @ORM\GeneratedValue(strategy="UUID")
     */
    protected $id;
}

例如，argument实体

<?php
// src/MyProject/MyBundle/Entity/Argument.php

namespace MyProject\MyBundle\Entity;

use Doctrine\ORM\Mapping as ORM;
use N1c0\OfficialtextBundle\Entity\Argument as BaseArgument;

/**
 * @ORM\Entity
 * @ORM\ChangeTrackingPolicy("DEFERRED_EXPLICIT")
 */
class Argument extends BaseArgument
{
    /**
     * @ORM\Id
     * @ORM\Column(type="guid", length=36)
     * @ORM\GeneratedValue(strategy="UUID")
     */
    protected $id;

    /**
     * Officialtext of this argument
     *
     * @var Officialtext 
     * @ORM\ManyToOne(targetEntity="MyProject\MyBundle\Entity\Argument")
     */
    protected $officialtext;
}

添加到app/config/config.yml

# N1c0OfficialtextBundle
n1c0_officialtext:
    db_driver: orm
    class:
        model:
            officialtext: MyProject\MyBundle\Entity\Officialtext
            argument: MyProject\MyBundle\Entity\Argument

entity_managers:
            default:
                mappings:
                    N1c0OfficialtextBundle: ~
                    MyBundleMyProjectBundle: ~

assetic:
    bundles:        ["N1c0OfficialtextBundle"]

步骤 3: 导入N1c0OfficialtextBundle路由文件

# /app/config/routing.yml
n1c0_officialtext:
    type: rest
    prefix: /api
    resource: "@N1c0Officialtext/Resources/config/routing.yml"

内容协商

每个资源都可通过不同的格式访问。

HTTP动词

对于officialtexts

GET

HTML格式

curl -i localhost:8000/api/v1/officialtexts/10

JSON格式

curl -i -H "Accept: application/json" localhost:8000/api/v1/officialtexts/10

POST

HTML格式

curl -X POST -d "n1c0_officialtext_officialtext%5Btitle%5D=myTitle&n1c0_officialtext_officialtext%5Bbody%5D=myBody" https://:8000/api/v1/officialtexts

JSON格式

curl -X POST -d '{"n1c0_officialtext_officialtext":{"title":"myTitle","body":"myBody"}}' https://:8000/api/v1/officialtexts.json --header "Content-Type:application/json" -v

PUT

JSON格式

curl -X PUT -d '{"n1c0_officialtext_officialtext":{"title":"myNewTitle","body":"myNewBody https://:8000/api/v1/officialtexts/10 --header "Content-Type:application/json" -v

对于arguments

GET

JSON格式

curl -i -H "Accept: application/json" localhost:8000/api/v1/officialtexts/10/arguments

POST

JSON格式

curl -X POST -d '{"n1c0_officialtext_argument":{"title":"myTitleArgument","body":"myBodyArgument"}}' https://:8000/api/v1/officialtexts/10/arguments.json --header "Content-Type:application/json" -v

PUT

JSON格式

curl -X PUT -d '{"n1c0_officialtext_argument":{"title":"myNewTitleArgument","body":"myNewBodyArgument"}}' https://:8000/api/v1/officialtexts/10/arguments/11.json --header "Content-Type:application/json" -v 

PATCH

JSON格式

curl -X PATCH -d '{"n1c0_officialtext_argument":{"title":"myNewTitleArgument"}}' https://:8000/api/v1/officialtexts/10/arguments/11.json --header "Content-Type:application/json" -v

HATEOAS REST

引入HATEOAS约束。

{
    "user": {
        "id": 10,
        "title": "myTitle",
        "body": "MyBody",
        "_links": {
            "self": { "href": "https://:8000/api/v1/officialtexts/10" }
        }
    }
}

FOSUserBundle集成

默认情况下，officialtexts是匿名的。可以使用FOSUserBundle认证来签名officialtexts。

A) 设置FOSUserBundle

首先您需要设置FOSUserBundle。检查说明。

B) 扩展Officialtext类

为了向officialtext添加作者，Officialtext类应实现SignedOfficialtextInterface并在映射中添加字段。

例如在ORM中

<?php
// src/MyProject/MyBundle/Entity/Officialtext.php

namespace MyProject\MyBundle\Entity;

use Doctrine\ORM\Mapping as ORM;
use N1c0\OfficialtextBundle\Entity\Officialtext as BaseOfficialtext;
use N1c0\OfficialtextBundle\Model\SignedOfficialtextInterface;
use Symfony\Component\Security\Core\User\UserInterface;

/**
 * @ORM\Entity
 */
class Officialtext extends BaseOfficialtext implements SignedOfficialtextInterface
{
    // .. fields

    /**
     * Authors of the officialtext
     *
     * @ORM\ManyToMany(targetEntity="Application\UserBundle\Entity\User")
     * @var User
     */
    protected $authors;

    public function __construct()
    {
        $this->authors = new \Doctrine\Common\Collections\ArrayCollection();
    }

    /**
     * Add author 
     *
     * @param Application\UserBundle\Entity\User $user
     */
    public function addAuthor(\Application\UserBundle\Entity\User $user)
    {
        $this->authors[] = $user;
    }

    /**
     * Remove user
     *
     * @param Application\UserBundle\Entity\User $user
     */
    public function removeUser(\Application\UserBundle\Entity\User $user)
    {
        $this->authorss->removeElement($user);
    }

    public function getAuthors()
    {
        return $this->authors;
    }

    public function getAuthorsName()
    {
        return $this->authors ?: parent::getAuthorsName(); 
    }
}

步骤 7: 添加基于角色的ACL安全性

注意

此包支持不同的安全设置。您还可以查看添加Symfony2的内置ACL安全。

OfficialtextBundle还提供了根据特定用户的角色配置权限的能力。请参见以下配置示例，了解如何自定义用于权限的默认角色。

要配置基于角色的安全性，请覆盖Acl服务

# app/config/config.yml

n1c0_officialtext:
    acl: true
    service:
        acl:
            officialtext:  n1c0_officialtext.acl.officialtext.roles
        manager:
            officialtext:  n1c0_officialtext.manager.officialtext.acl

要更改特定操作所需的角色，修改acl_roles配置密钥

# app/config/config.yml

n1c0_officialtext:
    acl_roles:
        officialtext:
            create: IS_AUTHENTICATED_ANONYMOUSLY
            view: IS_AUTHENTICATED_ANONYMOUSLY
            edit: ROLE_ADMIN
            delete: ROLE_ADMIN

使用标记解析器

N1c0Officialtext包允许开发者实现RawOfficialtextInterface，这将告诉包您的officialtexts将解析为标记语言。

您还需要在数据库中配置rawBody字段以存储解析后的officialtexts。

use N1c0\OfficialtextBundle\Model\RawOfficialtextInterface;

class Officialtext extends BaseOfficialtext implements RawOfficialtextInterface
{
    /**
     * @ORM\Column(name="rawBody", type="text", nullable=true)
     * @var string
     */
    protected $rawBody;
    
    ... also add getter and setter as defined in the RawOfficialtextInterface ...
}

当添加评论时，它会进行解析，并且调用setRawBody()，将评论的原始版本存储在数据库中，并在稍后渲染officialtext时显示。

支持任何标记语言，您只需要一个实现Markup\ParserInterface的桥梁类，它返回要显示在页面上的officialtext的原始html解析结果。

要设置自己的自定义标记解析器，您需要定义一个实现上述接口的服务，并告诉 N1c0OfficialtextBundle，相应地调整配置。

# app/config/config.yml

n1c0_officialtext:
    service:
        markup: your_markup_service

例如，使用 Sundown PECL 扩展作为标记服务

N1c0OfficialtextBundle 中的标记系统非常灵活，允许您使用任何存在解析器的语法语言。PECL 提供了一个名为 Sundown 的 markdown 解析器扩展，比纯 PHP 实现的 markdown 解析器更快。

N1c0OfficialtextBundle 并不包含此扩展的桥接器，但实现起来非常简单。

首先，您需要使用 PECL 安装 Sundown。 pecl install sundown。

您需要在您的应用程序包中创建以下服务。

<?php
// src/Vendor/OfficialtextBundle/Markup/Sundown.php

namespace Vendor\OfficialtextBundle\Markup;

use N1c0\OfficialtextBundle\Markup\ParserInterface;
use Sundown\Markdown;

class Sundown implements ParserInterface
{
    private $parser;

    protected function getParser()
    {
        if (null === $this->parser) {
            $this->parser = new Markdown(
                new \Sundown\Render\HTML(array('filter_html' => true)),
                array('autolink' => true)
            );
        }

        return $this->parser;
    }

    public function parse($raw)
    {
        return $this->getParser()->render($raw);
    }
}

以下是为启用此解析器桥接器而定义的服务

# app/config/config.yml

services:
    # ...
    markup.sundown_markdown:
        class: Vendor\OfficialtextBundle\Markup\Sundown
    # ...

n1c0_officialtext:
    # ...
    service:
        markup: markup.sundown_markdown
    # ...

另一个示例，使用 Pandoc 作为标记服务

Pandoc 是一个 Haskell 程序，允许您将文档从一种格式转换为另一种格式。更多信息请参阅 Pandoc。

要安装 Pandoc，请运行以下命令

$ apt-get install pandoc

有关 Pandoc 安装的更多信息，请参阅 Pandoc 安装。

我们还需要一个简单的 PHP 包装器。安装 Pandoc PHP 的推荐方法是使用 composer

{
    "require": {
        "ryakad/pandoc-php": "dev-master"
    }
}

安装完成后，您可以创建类似以下的服务标记

<?php

namespace vendor\OfficialtextBundle\Markup;

use N1c0\OfficialtextBundle\Markup\ParserInterface;
use Pandoc\Pandoc;

class MarkupPandoc implements ParserInterface
{
    private $parser;

    protected function getParser()
    {
        if (null === $this->parser) {
            $this->parser = new Pandoc();        
        }

        return $this->parser;
    }

    public function parse($raw)
    {
        return $this->getParser()->convert($raw, "markdown", "html");
    }
}

以下是为启用此解析器桥接器而定义的服务

# app/config/config.yml

services:
    # ...
    markup.pandoc_markdown:
        class: Vendor\OfficialtextBundle\Markup\MarkupPandoc
    # ...

n1c0_officialtext:
    # ...
    service:
        markup: markup.pandoc_markdown
    # ...

FOSCommentBundle 的集成

在 src/MyProject/MyBundle/Resources/views/Officialtext/getOfficialtexts.html.twig 中添加

<a href="{{ path('api_1_get_officialtext_thread', {'id': officialtext.id}) }}">Commentaires</a>

作为额外奖励的文档（NelmioApiDocBundle）

访问 https://:8000/api/doc。