README

用于管理论文的捆绑包。

步骤 1: 设置捆绑包

A) 下载并安装N1c0Dissertation

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

$ php composer.phar require n1c01a5/n1c0dissertation-bundle

B) 启用捆绑包

在内核中启用所需的捆绑包

<?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\DissertationBundle\N1c0DissertationBundle(),
    );
}

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

C) 启用Http方法覆盖

按照以下说明启用HTTP方法覆盖

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

# app/config/config.yml

framework:
    http_method_override: true

步骤 2: 设置Doctrine ORM映射

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

例如，论文实体

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

namespace MyProject\MyBundle\Entity;

use Doctrine\ORM\Mapping as ORM;
use N1c0\DissertationBundle\Entity\Dissertation as BaseDissertation;

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

例如，论点实体

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

namespace MyProject\MyBundle\Entity;

use Doctrine\ORM\Mapping as ORM;
use N1c0\DissertationBundle\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;

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

在app/config/config.yml中添加

# N1c0DissertationBundle
n1c0_dissertation:
    db_driver: orm
    class:
        model:
            dissertation: MyProject\MyBundle\Entity\Dissertation
            argument: MyProject\MyBundle\Entity\Argument

entity_managers:
            default:
                mappings:
                    N1c0DissertationBundle: ~
                    MyBundleMyProjectBundle: ~

assetic:
    bundles:        ["N1c0DissertationBundle"]

步骤 3: 导入N1c0DissertationBundle路由文件

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

内容协商

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

HTTP动词

对于论文

GET

以HTML格式

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

以JSON格式

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

POST

以HTML格式

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

以JSON格式

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

PUT

以JSON格式

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

对于论点

GET

以JSON格式

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

POST

以JSON格式

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

PUT

以JSON格式

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

PATCH

以JSON格式

curl -X PATCH -d '{"n1c0_dissertation_argument":{"title":"myNewTitleArgument"}}' https://:8000/api/v1/dissertations/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/dissertations/10" }
        }
    }
}

与FOSUserBundle集成

默认情况下，论文是匿名的。可以使用FOSUserBundle身份验证来签名论文。

A) 设置FOSUserBundle

首先，您必须设置 FOSUserBundle。请参阅说明。

B) 扩展Dissertation类

为了给论文添加作者，Dissertation类应该实现SignedDissertationInterface并在映射中添加一个字段。

例如，在ORM中

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

namespace MyProject\MyBundle\Entity;

use Doctrine\ORM\Mapping as ORM;
use N1c0\DissertationBundle\Entity\Dissertation as BaseDissertation;
use N1c0\DissertationBundle\Model\SignedDissertationInterface;
use Symfony\Component\Security\Core\User\UserInterface;

/**
 * @ORM\Entity
 */
class Dissertation extends BaseDissertation implements SignedDissertationInterface
{
    // .. fields

    /**
     * Authors of the dissertation
     *
     * @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安全性。

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

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

# app/config/config.yml

n1c0_dissertation:
    acl: true
    service:
        acl:
            dissertation:  n1c0_dissertation.acl.dissertation.roles
        manager:
            dissertation:  n1c0_dissertation.manager.dissertation.acl

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

# app/config/config.yml

n1c0_dissertation:
    acl_roles:
        dissertation:
            create: IS_AUTHENTICATED_ANONYMOUSLY
            view: IS_AUTHENTICATED_ANONYMOUSLY
            edit: ROLE_ADMIN
            delete: ROLE_ADMIN

使用标记解析器

N1c0Dissertation捆绑包允许开发者实现RawDissertationInterface，这将告诉捆绑包您的论文将被解析为标记语言。

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

use N1c0\DissertationBundle\Model\RawDissertationInterface;

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

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

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

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

# app/config/config.yml

n1c0_dissertation:
    service:
        markup: your_markup_service

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

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

N1c0DissertationBundle不附带该扩展的桥梁，但实现起来非常简单。

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

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

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

namespace Vendor\DissertationBundle\Markup;

use N1c0\DissertationBundle\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\DissertationBundle\Markup\Sundown
    # ...

n1c0_dissertation:
    # ...
    service:
        markup: markup.sundown_markdown
    # ...

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

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

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

$ apt-get install pandoc

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

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

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

安装完毕后，您可以创建一个类似于以下的服务标记

<?php

namespace vendor\DissertationBundle\Markup;

use N1c0\DissertationBundle\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\DissertationBundle\Markup\MarkupPandoc
    # ...

n1c0_dissertation:
    # ...
    service:
        markup: markup.pandoc_markdown
    # ...

FOSCommentBundle的集成

在src/MyProject/MyBundle/Resources/views/Dissertation/getDissertations.html.twig中添加

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

作为奖励的文档（NelmioApiDocBundle）

转到https://:8000/api/doc。