README

概览

symfony2-paypal-ipn是一个用于处理PayPal IPN（即时支付通知）服务的Symfony2包。该包充当PayPal IPN服务的监听器，并使用Doctrine将收到的订单记录到您的数据库中。发送订单确认邮件也非常简单（有关详细信息，请参阅[示例Twig电子邮件控制器] twigcontroller）。

symfony2-paypal-ipn可在Packagist packagist、KnpBundles knpbundles以及GitHub上获取。

描述

symfony2-paypal-ipn是[codeigniter-paypal-ipn] codeigniterpaypalipn的直接移植，这是一个为CodeIgniter用户提供的等效库，也是Orderly Ltd.的产品。

这个库（在Symfony语言中称为"bundle"）专注于"支付后"的工作流程，即在支付完成后，PayPal将即时支付通知调用发送到IPN控制器所需的处理。

此库处理以下内容

验证IPN调用
记录IPN调用
从IPN调用中提取订单和行项目信息
解释PayPal的支付状态
将订单和行项目存储到数据库中
触发一个事件，以便其他包可以执行其操作

所有预支付功能（例如，将结账信息发布到PayPal）和自定义后支付工作流程（例如，发送电子邮件）都留给读者练习。如果您需要一个更通用的用于处理PayPal的Symfony2工具包，请参阅[JMSPaymentPaypalBundle] jmspaymentbundle。

此库还支持从支付数据传输（PDT）获取状态。

依赖项

Symfony PayPal IPN Bundle依赖于Symfony2 symfony2、[Doctrine 2.0] doctrine2.0和curl。

提供了一个使用Twig twig模板语言的示例订单确认电子邮件。

安装

1. 从GitHub安装

我们将直接将PayPalIPNBundle安装到您的Symfony vendor目录中

$ cd {{YOUR SYMFONY APP}}/vendor
$ git clone git://github.com/orderly/symfony2-paypal-ipn.git
...
$ mv symfony2-paypal-ipn orderly

现在，至关重要的OrderlyPayPalIpnBundle.php文件应该在这里可用

{{YOUR SYMFONY APP}}/vendor/orderly/src/Orderly/PaypalIpnBundle/OrderlyPayPalIpnBundle.php

2. 注册包

现在我们需要注册新的包。编辑您的AppKernel.php文件

{{YOUR SYMFONY APP}}/app/AppKernel.php

并在registerBundles()方法中的$bundles数组末尾添加以下行

new Orderly\PayPalIpnBundle\OrderlyPayPalIpnBundle(),

现在编辑您的autoload.php文件

{{YOUR SYMFONY APP}}/app/autoload.php

并在您的registerNamespaces()调用末尾添加以下行

'Orderly'          => __DIR__.'/../vendor/orderly/src',

3. 部署数据库表

使用PayPalIPN Bundle，您可以选择将数据存储在MySQL等合理数据库中，或者使用MongoDB。下一节提供了如何使用这两个不同系统的信息。

3.1 使用ORM（MySQL）部署数据库表

如果您打算使用MySQL这样的合理数据库系统，您必须配置驱动程序以使用doctrine ORM。您可以通过将以下配置添加到您的bundle配置中来实现这一点

orderly_pay_pal_ipn:
    # ... Rest of the configuration
    drivers:
        orm:
            object_manager: doctrine.orm.entity_manager
            classes: ~

下一步是更新/创建PayPalIpnBundle所需的必要数据库表。有三种不同的方式部署三个数据库表

使用Symfony控制台

您可以使用以下命令在项目控制台中安装表

$ php app/console doctrine:schema:update --force

注意，此方法不会复制SQL文件中找到的表字段注释。

手动运行MySQL脚本

或者，您可以对数据库运行create_mysql_tables.sql MySQL文件。您可以在以下位置找到该文件

Orderly/PayPalIpnBundle/Resources/config

如果您选择此选项，您可能需要在运行之前修改每个表的DEFAULT CHARSET（当前设置为“utf8”）。

3.2 使用ODM（MongoDB）部署数据库表

要使用MongoDB作为数据存储，在使用ODM驱动程序激活您的部分之前，请确保安装了DoctrineMongoDBBundle。有关如何配置bundle的更多信息，请参阅Symfony2网站。

orderly_pay_pal_ipn:
    #....
    drivers:
        odm:
            object_manager: doctrine.odm.mongodb.document_manager
            classes: ~

注意：完整配置示例可以在4.1 使用MongoDB后端下找到

创建数据库表

通过运行以下命令将创建/更新MonogoDB集合

$ php app/console doctrine:mongodb:update --force

4. 配置

现在我们需要配置bundle。将以下内容添加到您的Symfony2 YAML配置文件app/config/config.yml中

# PaypalIpnBundle Configuration
orderly_pay_pal_ipn:

    # If set to false then service loads settings with "sandbox_" prefix
    islive:  false

    # Constants for the live environment (default settings in Configuration.php)
    email:    sales@CHANGEME.com
    url:      https://www.paypal.com/cgi-bin/webscr
    proxy:    ~
    debug:    %kernel.debug%
    pdttoken: pdt-token

    # Constants for the sandbox environment (default settings in Configuration.php)
    sandbox_email:       system_CHANGEME_biz@CHANGEME.com
    sandbox_url:         https://www.sandbox.paypal.com/cgi-bin/webscr
    sandbox_proxy:       ~
    sandbox_debug:       true
    sandbox_response:    VERIFIED
    sandbox_pdttoken:    pdt-token
    sandbox_pdtresponse:
        payment_status: Completed
        mc_gross: 123.00

    drivers:
        orm:
            object_manager: doctrine.orm.entity_manager
            classes: ~

请确保更新email和sandbox_email设置为您自己的PayPal账户。

当islive设置为false时，以下配置可以激活

sandbox_response允许您模拟IPN PayPal的响应。如果您不设置其值，您的服务器将击中PayPal服务器，并很可能返回INVALID。
sandbox_pdtresponse允许您模拟PDT PayPal的响应。如果您不设置其值，您的服务器将击中PayPal服务器，并很可能返回FAIL。要模拟值，只需传递服务器返回的键值对列表即可。

关于debug设置的一点说明：如果设置为true，则PayPalIpnBundle将存储最后一次具有IPN数据的IPN访问（即POST变量）到数据库中。然后，当您直接访问不带数据的IPN URL时，它将重新加载缓存的数据。因此，它实际上是一个“回放”模式，让您直接检查validateIPN() IPN处理器正在做什么。

4.1 使用MongoDB后端

要使用MongoDB后端与IPN监听器一起使用，请将驱动程序部分更改为odm并提供您的MongoDB对象管理器的名称。以下是一个基本的配置示例。

# PaypalIpnBundle Configuration
orderly_pay_pal_ipn:

    # If set to false then service loads settings with "sandbox_" prefix
    islive:  false

    # Constants for the live environment (default settings in Configuration.php)
    email:    sales@CHANGEME.com
    url:      https://www.paypal.com/cgi-bin/webscr
    proxy:    ~
    debug:    %kernel.debug%
    pdttoken: pdt-token

    # Constants for the sandbox environment (default settings in Configuration.php)
    sandbox_email:       system_CHANGEME_biz@CHANGEME.com
    sandbox_url:         https://www.sandbox.paypal.com/cgi-bin/webscr
    sandbox_proxy:       ~
    sandbox_debug:       true
    sandbox_response:    VERIFIED
    sandbox_pdttoken:    pdt-token
    sandbox_pdtresponse:
        payment_status: Completed
        mc_gross: 123.00

    drivers:
        odm:
            object_manager: doctrine.odm.mongodb.document_manager
            classes: ~

5. 设置路由（可选但推荐）

首先打开以下文件，告诉Symfony的路由系统在哪里可以找到我们的示例控制器

{{YOUR SYMFONY APP}}/app/config/routing.yml

使用Twig发送订单确认

假设您想使用Twig发送订单确认电子邮件，请添加以下控制器

OrderlyPayPalIpnBundleEmail:
    resource: "@OrderlyPayPalIpnBundle/Controller/TwigNotificationEmailController.php"
    type:     annotation
    prefix:   /ipn/

您的网站现在将监听在URL上的即时支付通知

http://{{YOUR DOMAIN}}/ipn/ipn-twig-email-notification

请注意，提供的示例电子邮件模板依赖于Twig的[number_format] numberformat过滤器，该过滤器于2012年12月添加（您可能需要更新您的Twig版本才能使用此功能）。别忘了告诉PayPal您的新PayPal IPN URL。

仅记录订单而不发送通知

或者，如果您只想在数据库中记录订单（而不发送任何通知），那么请在此控制器中添加

OrderlyPayPalIpnBundleNoEmail:
    resource: "@OrderlyPayPalIpnBundle/Controller/NoNotificationController.php"
    type:     annotation
    prefix:   /ipn/

您的网站现在将监听以下IPN

http://{{YOUR DOMAIN}}/ipn/ipn-no-notification

别忘了告诉PayPal您的新的PayPal IPN URL。

免责声明：提供的示例控制器完全是示例。在使用此捆绑包之前，请使用您自己的业务逻辑更新其中一个或多个示例文件。

要接收PDT变量

这是您的PDT调用可能看起来像的示例。

namespace Your\OwnBundle;

use Symfony\Bundle\FrameworkBundle\Controller\Controller;

class YourPaypalController extends Controller {
    /**
     * Your return action from Paypal.
     */
    public function completeAction() {
        $tx = $this->getRequest()->get('tx');
        if (!$tx) {
            // Redirect to a non-found page
            return $this->redirect($this->generateUrl('notFound'));
        }

        $pdt = $this->get('orderly_pay_pal_pdt');
        $pdtArray = $pdt->getPdt($tx);

        $status = 'unknown';
        if (isset($pdtArray['payment_status'])) {
            $status = $pdtArray['payment_status'];
        }

        return $this->render('YourOwnBundle:YourPaypal:complete.html.twig',
            array('status' => $status)
        );
    }
}

6. 订阅事件（如果您需要自定义处理）

在接收到IPN并验证其有效性后，将分派一个带有传入IPN的事件。然后，您可以订阅一个监听器并执行所需的任何操作。使用类似以下内容更改您的 config.yml

services:
    # ...

    paypal_im_received:
        class: Your\OwnBundle\Event\YourPayPalListener
        arguments: ["@doctrine.orm.entity_manager"]
        tags:
            - { name: kernel.event_listener, event: paypal.ipn.receive, method: onIPNReceive }

现在您只需编写您的自定义监听器

namespace Your\OwnBundle\Event;

use Orderly\PayPalIpnBundle\Event\PayPalEvent;
use Doctrine\Common\Persistence\ObjectManager;

class YourPayPalListener {

    private $om;

    public function __construct(ObjectManager $om) {
        $this->om = $om;
    }

    public function onIPNReceive(PayPalEvent $event) {
        $ipn = $event->getIPN();
        // do your stuff
    }
}

7. 测试和故障排除

现在是时候进行测试了。首先，请确保将 islive 设置为 false，将 sandbox_debug 设置为 true。

一旦启用调试，测试方法如下

按照常规进行结账流程，进行PayPal沙盒支付等
PayPal将发送IPN POST数据到您的新的PayPal IPN URL
检查PayPal IPN历史记录以确定成功或失败（例如，HTTP状态代码500）
检查您是否收到订单确认电子邮件（如果您发送了电子邮件）
检查订单和行项目是否存储在您的数据库中

如果您的任何检查出现问题，则下一步是手动在浏览器中调用您的IPN URL并查看发生了什么（例如PHP或Symfony错误，或者可能是数据库或Twig未找到错误）。这是因为步骤3中解释的调试“重放”功能。接下来

修复错误
重复

8. 完整配置

# PaypalIpnBundle Configuration
orderly_pay_pal_ipn:

    # If set to false then service loads settings with "sandbox_" prefix
    islive:  false

    # Constants for the live environment (default settings in Configuration.php)
    email:    sales@CHANGEME.com
    url:      https://www.paypal.com/cgi-bin/webscr
    proxy:    ~
    debug:    %kernel.debug%
    pdttoken: pdt-token

    # Constants for the sandbox environment (default settings in Configuration.php)
    sandbox_email:       system_CHANGEME_biz@CHANGEME.com
    sandbox_url:         https://www.sandbox.paypal.com/cgi-bin/webscr
    sandbox_proxy:       ~
    sandbox_debug:       true
    sandbox_response:    VERIFIED
    sandbox_pdttoken:    pdt-token
    sandbox_pdtresponse:
        payment_status: Completed
        mc_gross: 123.00

    drivers: # Define one driver only.
        orm:
            object_manager: doctrine.orm.entity_manager
            classes:
                ipn_log: Orderly\PayPalIpnBundle\Entity\IpnLog
                ipn_order_items: Orderly\PayPalIpnBundle\Entity\IpnOrderItems
                ipn_orders: Orderly\PayPalIpnBundle\Entity\IpnOrders
        # OR for MongoDB support
        odm:
            object_manager: doctrine.odm.mongodb.document_manager
            classes:
                ipn_log: Orderly\PayPalIpnBundle\Document\IpnLog
                ipn_order_items: Orderly\PayPalIpnBundle\Document\IpnOrderItems
                ipn_orders: Orderly\PayPalIpnBundle\Document\IpnOrders

支持和错误

对于支持请求，请发送电子邮件至[Orderly Ltd] orderlyemail。如果您认为库中存在错误，或者您希望添加的功能缺失，请创建一个[新GitHub问题] newissue。

致谢

此库是[Codeigniter PayPal IPN库] codeigniterpaypalipn的移植，也由Orderly Ltd发布。

感谢所有为symfony2-paypal-ipn做出贡献的人

作者： Kemor kemor
贡献者： Strife strife
贡献者：[Alex Dean] alexdean
贡献者：[Ivo Azirjans] ivoaz
贡献者：[Alexander Pirsig] piscis
贡献者：[Carles Climent] carlescliment

免责声明和警告

Orderly Ltd不对通过使用Symfony2 PayPal IPN Bundle产生的任何处理错误或由此产生的任何财务损失承担责任。

特别是，此库不满足PayPal IPN的要求

验证实际支付金额是否与您打算收取的金额相符。虽然这并非IPN问题，但如果您不加密按钮，其他人可能截取原始传输并更改价格。如果没有这项检查，您可能会接受比预期更少的支付。

（此验证步骤不包含在此套餐范围内，因为它需要与您的产品目录集成。）

此外，此库未能正确处理退款。通常退款会以新的订单行存储在 ipn_orders 中，并带有负余额，但这也不是100%可预测的。

版权

许可证

根据Apache License，版本2.0（以下简称“许可证”）许可；除非符合许可证规定，否则不得使用此文件。您可以在以下地址获取许可证副本：

https://apache.ac.cn/licenses/LICENSE-2.0

除非适用法律要求或书面同意，否则在许可证下分发的软件按“原样”分发，不提供任何明示或暗示的保证。有关许可证下的具体权限和限制，请参阅许可证。

vkurko / paypal-ipn-bundle

维护者

详细信息