README

Laravel-Gigapay

Laravel-Gigapay 是 Gigapay API 的简单包装器。[链接](https://gigapay.co)。它提供辅助方法，使您使用 Gigapay API 变得简单、快捷和高效。

Laravel-Gigapay 管理资源，如 Employees、Invoices、Payouts、Pricing 和 Webhooks。

它使用 Gigapay 提供的 API，这里是它的 [API 文档](https://developer.gigapay.se)。

您还可以查看 [Postman 收集](https://documenter.getpostman.com/view/13692349/UyxkkR3T)，通过自己调用 API 来更好地理解它。

要了解 Gigapay 的事件流，您可以查看它的 [事件文档](https://developer.gigapay.se/#events)。

目录

• 安装
• 配置
• 员工
  • 列表
  • 创建
  • 检索单个
  • 更新
  • 替换
  • 删除
  • 重发邀请
  • 辅助工具
• 支付
  • 列表
  • 创建
  • 批量创建
  • 带有内联员工的创建
  • 检索单个
  • 删除
  • 重发
  • 辅助工具
• 发票
  • 列表
  • 检索单个
  • 更新
  • 删除
• 定价
  • 列表
  • 检索单个
  • 计算定价
  • 批量计算
• Webhook
  • 设置
  • 列表
  • 创建
  • 检索单个
  • 更新
  • 替换
  • 删除
• 列表资源
  • 分页
  • 搜索
  • 扩展资源
  • 添加过滤器
  • 获取 JSON 数据
• 异常处理
  • Gigapay 异常

安装

使用 composer 安装包

composer require mazimez/laravel-gigapay

发布配置文件

php artisan vendor:publish --provider="Mazimez\Gigapay\GigapayServiceProvider"

配置

发布的配置文件 config/gigapay.php 看起来像这样：

<?php

use Mazimez\Gigapay\Events\EmployeeClaimed;
use Mazimez\Gigapay\Events\EmployeeCreated;
use Mazimez\Gigapay\Events\EmployeeNotified;
use Mazimez\Gigapay\Events\EmployeeVerified;
use Mazimez\Gigapay\Events\InvoiceCreated;
use Mazimez\Gigapay\Events\InvoicePaid;
use Mazimez\Gigapay\Events\PayoutAccepted;
use Mazimez\Gigapay\Events\PayoutCreated;
use Mazimez\Gigapay\Events\PayoutNotified;

return [

    /*
    |--------------------------------------------------------------------------
    | Gigapay Server URL
    |--------------------------------------------------------------------------
    |
    | Gigapay generally has 2 servers, 1 for demo and 1 for production
    | both server has different url, by default it will use the demo server URL
    | but you can change it from your project's .env file.
    | also currently Gigapay's APIs are at version 2, so it will use version 2
    |
    */

    'server_url' => env('GIGAPAY_SERVER_URL', 'https://api.demo.gigapay.se/v2'),

    /*
    |--------------------------------------------------------------------------
    | Gigapay Token
    |--------------------------------------------------------------------------
    |
    | Gigapay uses this token to identify and authenticate requests,
    | you can get this Token from your Gigapay account
    | Note that Tokens are different for demo server and production server
    | define it in your .env.
    |
    */

    'token' => env('GIGAPAY_TOKEN'),

    /*
    |--------------------------------------------------------------------------
    | Gigapay integration id
    |--------------------------------------------------------------------------
    |
    | Integrations are like Transactions, it's a parent object of all other objects in the Gigapay API
    | whenever you do any action in Gigapay, it will be in integration and it has a integration id
    | Gigapay's API need integration id, you can create integration with Gigapay APIs from https://developer.gigapay.se/#create-an-integration
    |
    */

    'integration_id' => env('GIGAPAY_INTEGRATION_ID'),

    /*
    |--------------------------------------------------------------------------
    | Gigapay lang
    |--------------------------------------------------------------------------
    |
    | Language for the API responses. default will be english(en)
    |
    */

    'lang' => env('GIGAPAY_LANG', 'en'),


    /*
    |--------------------------------------------------------------------------
    | Gigapay events mapping
    |--------------------------------------------------------------------------
    |
    | mapping of Gigapay's different webhook events to route that will receive the webhook event
    |
    */

    'events_mapping' => [
        'Employee.created' => 'employee-created',
        'Employee.notified' => 'employee-notified',
        'Employee.claimed' => 'employee-claimed',
        'Employee.verified' => 'employee-verified',
        'Payout.created' => 'payout-created',
        'Payout.notified' => 'payout-notified',
        'Payout.accepted' => 'payout-accepted',
        'Invoice.created' => 'invoice-created',
        'Invoice.paid' => 'invoice-paid',
    ],

    /*
    |--------------------------------------------------------------------------
    | Gigapay Events
    |--------------------------------------------------------------------------
    |
    | List of Gigapay events that you can listen to by Listeners.
    |
    */

    'events_list' => [
        EmployeeClaimed::class,
        EmployeeCreated::class,
        EmployeeNotified::class,
        EmployeeVerified::class,
        InvoiceCreated::class,
        InvoicePaid::class,
        PayoutAccepted::class,
        PayoutCreated::class,
        PayoutNotified::class,
    ]
];

一旦配置文件就绪，您需要将一些变量添加到您的 .env 文件中。这里有 4 个变量：

• GIGAPAY_TOKEN = 您将从您的 Gigapay 账户获取此令牌
• GIGAPAY_INTEGRATION_ID = 您可以从您的 Gigapay 账户或从 [Gigapay API](https://developer.gigapay.se/#integrations) 获取此 ID
• GIGAPAY_SERVER_URL = Gigapay 有 2 个服务器，演示和生产。两个服务器的 URL 都可以在 [Gigapay 文档](https://developer.gigapay.se/#authentication) 中找到
• GIGAPAY_LANG = Gigapay 将以其响应或错误的语言

请注意，Gigapay 为每个服务器都有单独的令牌和集成 ID，因此每次切换服务器时，请记得更新 SERVER URL 以及令牌和集成 ID。

GIGAPAY_TOKEN="your-gigapay-account-token"
GIGAPAY_INTEGRATION_ID="yours-gigapay-account-integration-id"
GIGAPAY_SERVER_URL="https://api.demo.gigapay.se/v2"
GIGAPAY_LANG="en"

员工

员工是执行您组织内任务的个人，由 Gigapay 雇佣或分包。要将员工添加到您的组织，您可以创建员工对象。员工将收到通知，Gigapay 将验证他们的身份和工作许可。您可以从中了解更多信息。[Gigapay 文档](https://developer.gigapay.se/#employees)

employee-creation

• 要创建员工，您需要它的 name 和 email 或 cellphone_number，其他数据不是必需的。
• 您可以使用 create 方法通过传递所有数据作为参数来创建员工，您还可以使用 createByArray 方法，该方法接受包含相同数据的数组，在这种情况下，您只需添加所需的数据。
• 元数据是一个 Json 对象，因此请记住使用 json_encode() 方法。
• 您可以从 Gigapay 文档 获取有关员工对象更多信息。

use Mazimez\Gigapay\Employee;

//#1 creating Employee by passing all data in arguments
$employee = Employee::create(
            'jhone doe',  //employee's name (required)
            'test@gmail.com',  //employee's email (has to be unique)
            null,  //employee's phone number(proper swidish phone number, has to be unique)
            'SWE', //employee's country
            json_encode([
                "data" => "data from your system"  //any metadata that you want to add from you system(json encoded)
            ]),
            '1-2-3' //employee's ID(has to be unique)
        );
return $employee->getJson();

//#2 creating Employee by passing all data in an array
$employee = Employee::createByArray([
    "id"=>"1-2-3", //employee's ID(has to be unique)
    "name"=>"jhone doe", //employee's name (required)
    "email"=>"test@gmail.com", //employee's email (has to be unique)
    "metadata"=>json_encode([
        "data" => "data from your system" //any metadata that you want to add from you system(json encoded)
    ]),
    "cellphone_number"=>"123456789", //employee's phone number(proper swidish phone number, has to be unique)
    "country"=>"SWE", //employee's country
]);
return $employee->getJson();

getJson() 方法将返回员工对象的 JSON 格式。

employee-update

• 员工资源可以随时更新，可以更新的数据有 id、name、email、country、cellphone_number 和 metadata。
• 可以通过调用单独的方法或通过在员工对象上更新值然后调用 save() 方法来更新每个数据，以更新整个员工对象。
• 请记住在保存元数据之前使用 json_encode()。
• 此外，要更新员工的 ID，请使用单独的方法 updateId() 而不是 save()，因为 save() 将尝试更新具有当前 ID 的员工（在 Gigapay 数据库中不存在的新的 ID）。
• 唯一性和格式规则仍然适用。您可以从 Gigapay 文档 获取更多信息。

use Mazimez\Gigapay\Employee;

//#1: updating values using separate methods
$employee = Employee::findById('123'); //finding employee by id

$employee = $employee->updateCountry('SWE'); //updating country
$employee = $employee->updateName("test employee"); //updating name
$employee = $employee->updateEmail("jhone@doe.com"); //updating email
$employee = $employee->updateMetaDate(json_encode([
    "data" => "some more data from you system",  //updating metadata
]));
$employee = $employee->updateId('12354'); //updating id
return $employee->getJson();

//#2 updating values using save() methods
$employee = Employee::findById('dvsdvsdv'); //finding employee by id

$employee->country  = "SWE"; //updating country
$employee->name = "test employee"; //updating name
$employee->email = "jhone@32323doe.com"; //updating email
$employee->metadata = json_encode([
    "data" => "some more data from you system", //updating metadata
]);
$employee->save(); //saving the employee object
return $employee->getJson();

employee-list

Employee::list() 方法将返回员工的 ListResource，您可以使用它来应用过滤条件并搜索所有员工。您可以从 Gigapay 文档 获取更多信息。

use Mazimez\Gigapay\Employee;

$employees = Employee::list(); //getting list of employee
$employees = $employees->paginate(1, 5);  //add pagination
return $employees->getJson();

employee-retrieve

您可以通过 ID 获取任何员工。您可以从 Gigapay 文档 获取更多信息。

use Mazimez\Gigapay\Employee;

$employee = Employee::findById('1'); //getting employee by it's id
return $employee->getJson();

employee-replace

替换任何员工实际上会更改该员工的 ID 以及所有数据，包括您提供的数据。请注意，与该员工相关联的其他数据（如付款）将继续与其关联。因此，您不是在创建新的员工，而是可以用新数据替换现有的员工。有关更多信息，请参阅 Gigapay 文档。

use Mazimez\Gigapay\Employee;

$employee = Employee::findById('1'); //getting employee by it's id
$employee =  $employee->replace([ //replacing the employee with new data
    "id" => "1-2-3-4-5-6",
    "name" => "jhone doe",
    "email" => "testcdcdd@gmail.com",
    "metadata" => json_encode([
        "data" => "data from your system"
    ]),
    "country" => "SWE",
]);
return $employee->getJson(); //return the new employee instance

employee-delete

您可以通过在 Employee 实例上调用 destroy 方法来删除任何员工，但我们不能删除已注册 Payout 的员工。有关更多信息，请参阅 Gigapay 文档。

use Mazimez\Gigapay\Employee;

$employee = Employee::findById('1'); //getting employee by it's id
$employee->destroy(); //deletes the employee
return $employees->getJson(); //return the empty Employee instance

employee-resend

员工将收到一封加入的电子邮件，邮件地址是在创建员工时提供的。如果出现问题，我们也可以重新发送该邮件。重新发送后，您至少需要等待 24 小时才能再次重新发送。有关更多信息，请参阅 Gigapay 文档。

use Mazimez\Gigapay\Employee;

$employee = Employee::findById('1'); //getting employee by it's id
$employee->resend(); //resend invite to the employee

employee-helper

您可以在员工实例上使用一些辅助方法。例如

• getAllPayouts() 将返回该员工的 ListResource。

use Mazimez\Gigapay\Employee;

$employee = Employee::findById('1'); //getting employee by it's id
$payouts = $employee->getAllPayouts(); //gettin payouts for that perticular employee
return $payouts->getJson(); //returning the payouts in json

支付

要将 Payout 发送到员工，您需要创建一个 Payout 对象。当相应的发票付款后，员工会收到 Payout 通知。员工需要在资金发放到其账户之前签署并接受 Payout。您可以从 Gigapay 文档 获取更多信息。

payout-creation

• 要创建 Payout，您需要它的 amount、invoiced_amount 或 cost 中的任何一个数据。
• 您还需要添加 Employee id 和 description。此外，在开始支付员工的薪水（amount）之前，员工需要经过验证。
• 与 Employee 资源一样，Payout 也有两种创建方法。create 方法接收参数中的数据，而 createByArray 方法接收数组中的数据。
• 在提供元数据时，请记住使用 json_encode() 方法。
• 您可以从Gigapay 文档了解更多关于支付定价的信息。

use Mazimez\Gigapay\Payout;

//#1 creating payout with arguments
$payout = Payout::create(
            '9aa16b42-d0f3-420f-ba57-580c3c86c419', //employee id
            'Instagram samarbete 2021-11-13.', //description for payout
            120, //amount of payout
            null, //cost of payout
            null, //invoice amount of payout
            'SEK', //currency of payout
            json_encode([
                "data" => "data from your system" //metadata of payout
            ]),
            null, //The time at which the gig will start. Displayed as ISO 8601 string.
            null, //The time at which the gig will end. Displayed as ISO 8601 string.
            3 //Unique identifier for the object.
);
return $payout->getJson();

//#2 creating payout by array
$payout = Payout::createByArray([
            "employee" => "1-2-3", //employee id
            "invoiced_amount" => "120", //invoice amount of payout
            "description" => "test description", //description for payout
            "metadata" => json_encode([
                "data" => "data from your system" //metadata of payout
            ]),
            "currency"=>"SEK", //currency of payout
            "id"=>"payout-1-2-3" //Unique identifier for the object. 
        ]);
return $payout->getJson();

使用getJson()方法将返回以JSON格式表示的支付对象。

payout-inline-creation

• Gigapay还提供API来创建支付和员工。
• 在创建新的支付和员工时，请注意您应该使用invoiced_amount，因为其他类型的字段，如cost和amount需要员工经过验证，而由于这是新员工，所以在那个点不会经过验证。
• 如果您使用此API与某些现有员工一起，则也可以使用cost和amount，它不会创建新的员工，而只是将其与给定数据合并。
• 此方法的参数几乎与正常创建方法相同，只是现在您需要传递一个包含员工信息（如Employee email和name等）的数组，而不是员工ID。
• 您可以从Gigapay 文档获取更多信息。
• 感谢@rolandlluka建议此方法并添加了相关的pull-request。希望您还会提出更多改进建议😅

use Mazimez\Gigapay\Payout;

$payout = Payout::createInline(
            [
                "name" => "jhone dao", //name (required)
                "email" => "jhone@dau.com", //email (required)
                "country" => "SWE", //country(optional)
                "cellphone_number" => "+46760024938"//phone number(optional)
            ], //inline employee data
            'Instagram samarbete 2021-11-13.', //description for payout
            null, //amount of payout
            null, //cost of payout
            120, //invoice amount of payout
            'SEK', //currency of payout
            json_encode([
                "data" => "data from your system" //metadata of payout
            ]),
            null, //The time at which the gig will start. Displayed as ISO 8601 string.
            null, //The time at which the gig will end. Displayed as ISO 8601 string.
            3 //Unique identifier for the object.
);
return $payout->getJson();

payout-multiple-creation

• Gigapay还提供API，可以一次性创建多个支付。
• 所有这些支付都将添加到同一个发票对象中。
• 它接受支付对象结构中的数组（json）。
• 您至少需要提供employee-id、description以及amount、cost或invoice_amount中的一个。其他东西不是必需的。
• 您可以将支付创建为不同的员工。
• 您可以从Gigapay 文档获取更多信息。

use Mazimez\Gigapay\Payout;

//creating 3 payouts to 3 different employees (with different specification)
$data = collect();
//any logic for calculating the payout value
$data->push([
    "employee" => "employee-id-1",
    "description" => "test description",
    "invoiced_amount" => "210",
]);
//any logic for calculating the payout value
$data->push([
    "employee" => "employee-id-2",
    "description" => "test description",
    "cost" => "210",
    "country" => "SWE",
    "metadata" => [
        "data" => "data about your system"
    ],
]);
//any logic for calculating the payout value
$data->push([
    "id" => "test-id",
    "employee" => "employee-id-3",
    "description" => "test description",
    "amount" => "210",
    "country" => "SWE",
    "currency" => "SEK"
]);
//creating multiple payouts by giving the array
$payouts = Payout::createMultiple($data->toArray()); 
return $payouts; //returns an array of Payout objects

payout-list

Payout::list()方法将返回payouts的ListResource，您可以使用它来应用筛选器并在所有payout中进行搜索。您可以从Gigapay 文档获取更多信息。

use Mazimez\Gigapay\Payout;

$payouts = Payout::list(); //getting list of employee
$payouts = $payouts->paginate(1, 5);  //add pagination
return $payouts->getJson();

payout-retrieve

您可以通过其ID检索任何支付。您可以从Gigapay 文档获取更多信息。

use Mazimez\Gigapay\Payout;

$payout = Payout::findById('1'); //getting payout by it's id
return $payout->getJson();

payout-delete

您可以通过在Payout实例上调用destroy方法来删除任何支付，但我们不能删除属于已付款发票或信用发票的支付。有关更多信息，请参阅Gigapay 文档。

use Mazimez\Gigapay\Payout;

$payout = Payout::findById('1'); //getting payout by it's id
$payout->destroy(); //deletes the payout
return $payout->getJson(); //return the empty payout instance

payout-resend

一旦支付已支付，员工应该会收到关于其支付的邮件。您也可以使用支付实例上的resend()方法重新发送邮件。请注意，只有在支付已支付后才能发送邮件。您可以从Gigapay 文档获取更多信息。

use Mazimez\Gigapay\Payout;

$payout = Payout::findById('89f9cfbe-f1ec-4d17-a895-21cdb584eb4d'); //getting payout by it's id
$payout->resend(); //resend mail to the employee

payout-helper

您可以在支付实例上使用一些辅助方法。例如

• expandInvoice()此方法将扩展支付上的发票字段，并给出整个发票的JSON数据。
• expandEmployee()此方法将扩展支付上的员工字段，并给出整个员工的JSON数据。

您还可以将此方法链在同一支付实例上。

use Mazimez\Gigapay\Payout;

$payout = Payout::findById('89f9cfbe-f1ec-4d17-a895-21cdb584eb4d'); //getting payout by it's id
$payout->expandInvoice()->expandEmployee();//expanding invoice and employee field
return $payout->getJson(); //returning the payouts in json(with expanded values)

invoice

发票会将付款分组。它是一个管理对象，您不能直接创建它们。当创建一个付款时，它将被添加到当前打开的发票中。如果没有打开的发票，将创建一个新的。您可以从中了解更多信息：Gigapay文档

invoice-list

使用Invoice::list()方法将返回ListResource，用于对所有发票应用筛选和搜索。您可以从Gigapay文档中获取更多信息。

use Mazimez\Gigapay\Invoice;

$invoices = Invoice::list(); //getting list of invoices
$invoices = $invoices->paginate(1, 5);  //add pagination
return $invoices->getJson();

invoice-retrieve

您可以按其id检索任何发票。您可以从Gigapay文档中获取更多信息。

use Mazimez\Gigapay\Invoice;

$invoice = Invoice::findById('f3ee8cb8-fc95-4ea2-9b2e-18875b0d759a');//getting invoice by it's ID
return $invoice->getJson();

invoice-update

• 发票资源中可以更新的唯一字段是id和metadata。
• 就像Employee一样，它们有专门的方法，并且还有一个save()方法，该方法将使用Gigapay更新整个实例。
• 为了更新发票的ID，请使用单独的方法updateId()而不是save()，因为save()将尝试使用当前ID（不存在于Gigapay数据库中的新ID）更新发票。

use Mazimez\Gigapay\Invoice;

//#1: updating values using separate methods
$invoice = Invoice::findById('4bb6bd41-643e-43fe-af09-206c755088c9');
$invoice = $invoice->updateId("123");  //updating id
$invoice =$invoice->updateMetaDate(json_encode([
    "data" => "data from your system" //updating metadata
]));

//#2 updating values using save() methods
$invoice->metadata = json_encode([
    "data" => "data from your system" //updating metadata
]);
$invoice->save();

invoice-delete

您可以通过在发票实例上调用destroy方法来删除任何发票，但我们不能删除已付款的发票或信用发票。更多信息请参见Gigapay文档。

use Mazimez\Gigapay\Invoice;

$invoice = Invoice::findById('f3ee8cb8-fc95-4ea2-9b2e-18875b0d759a');//getting invoice by it's ID
$invoice->destroy(); //deletes the invoice
return $invoice->getJson(); //return the empty invoice instance

定价

• 定价资源允许您计算您想进行的付款的价格，以及检索先前已进行的付款的价格信息。该资源旨在尽可能多地模仿付款资源，例如，可以使用相同的请求检索您想要进行的付款的价格信息，并实际进行它。
• 使用amount、invoiced_amount或cost中的任何一个作为计算定价分解的基础。
• 一个是提供的，其他的是基于此计算的。它们的定义如下：

1. amount：支付金额加上收件人支付的义务。
2. invoiced_amount：amount加上雇主支付的义务。
3. cost：invoiced_amount加上Gigapay的费用。这是您最终支付的金额。

Pricing-List

Pricing::list()方法将返回ListResource，用于应用筛选。您可以从Gigapay文档中获取更多信息。

use Mazimez\Gigapay\Pricing;

$pricing = Pricing::list(); //getting list of pricing
$pricing = $pricing->paginate(1, 5);  //add pagination
return $pricing->getJson();

Pricing-Retrieve

您可以通过付款的id检索任何付款的定价信息。您可以从Gigapay文档中获取更多信息。

use Mazimez\Gigapay\Pricing;

$pricing = Pricing::findById('89f9cfbe-f1ec-4d17-a895-21cdb584eb4d')//getting pricing info by payout's ID
return $pricing->getJson();

Pricing-Calculate

• 定价资源主要帮助您在实际上进行付款之前计算付款。您可以使用Pricing::calculatePricing方法计算任何付款，而无需实际进行。
• 在计算定价时，您需要提供employee_id以及您想要支付的金额，您可以根据需要提供amount、cost或invoiced_amount。

use Mazimez\Gigapay\Pricing;

$pricing = Pricing::calculatePricing(
        '0d42728d-b565-402d-80aa-a20bec94a9a2', //id of employee that you want to pay
        'SEK', //currency of payout
        null, //cost (only 1 out cost, amount and invoiced_amount is allowed)
        '120', //amount (only 1 out cost, amount and invoiced_amount is allowed)
        null, //invoiced_amount (only 1 out cost, amount and invoiced_amount is allowed)
        'test', //description
        false, //full_salary_specification
        json_encode([
            "data" => "data from your system" //metadata of payout
        ]), 
        null, //start_at
        null, //end_at
        null, //id
    );
return $pricing->getJson();
    

pricing-calculate-bulk

• Gigapay还提供API以批量计算付款（一次性进行多次付款）。
• 它接受支付对象结构中的数组（json）。
• 您至少需要提供employee-id和amount、cost或invoice_amount中的一个。其他内容不是必需的（description也不是必需的）。
• 然后您可以一起计算不同员工的价格。
• 更多信息请参见Gigapay文档。

use Mazimez\Gigapay\Pricing;

//calculating pricing info for 3 different payouts to 3 different employees (with different specifications)
$pricings =  Pricing::calculateBulk([
            [
                "employee" => "employee-id-1",
                "invoiced_amount" => "210",
            ],
            [
                "employee" => "employee-id-2",
                "description" => "test description",
                "cost" => "210",
                "country" => "SWE",
            ],
            [
                "id" => "test-id",
                "employee" => "employee-id-3",
                "description" => "test description",
                "amount" => "210",
                "country" => "SWE",
                "currency" => "SEK"
            ],
        ]);
return $pricings; //returns an array of pricing objects

Webhook

• Webhooks 允许您在您的 Gigapay 账户上发生任何事件时接收实时状态更新。基本上，它会发送您执行操作的资源的详细信息。
• 总共有9个事件，您可以从Gigapay 文档获取更多信息。
• laravel-gigapay 通过 Laravel 事件 提供了一种简单的方式来处理所有这些 Webhooks。laravel-gigapay 可以在任何 Webhook 发送数据时触发事件。然后，您可以通过 监听器 来监听这些事件。

webhook-setup

• 为了接收 Webhooks 并使用监听器，您需要首先在您的 Laravel 项目中设置一些东西。

1. App URL：首先，如果您尚未设置，需要将 .env 文件中的 APP_URL 设置，因为此 URL 将用于注册 Webhooks。

APP_URL="https://youwebsite.url"

1. 事件发现：为了使您的监听器能够直接从 larave-gigapay 发现事件，您需要启用自动发现。

• 您可以通过访问项目的 EventServiceProvider 并将方法 shouldDiscoverEvents 返回 true 来做到这一点。

/**
* Determine if events and listeners should be automatically discovered.
*
* @return bool
*/
public function shouldDiscoverEvents()
{
    return true;
}

• 如果您不想启用自动发现（或您的 Laravel 版本不支持自动发现），您也可以手动将这些监听器添加到 $listen 数组中。

protected $listen = [
    Registered::class => [
        SendEmailVerificationNotification::class, //default email verification listener
    ],
    //adding our listeners
    EmployeeClaimed::class => [
        EmployeeClaimedListener::class, 
    ],
    EmployeeCreated::class => [
        EmployeeCreatedListener::class,
    ],
    EmployeeNotified::class => [
        EmployeeNotifiedListener::class,
    ],
    EmployeeVerified::class => [
        EmployeeVerifiedListener::class,
    ],
    InvoiceCreated::class => [
        InvoiceCreatedListener::class,
    ],
    InvoicePaid::class => [
        InvoicePaidListener::class,
    ],
    PayoutAccepted::class => [
        PayoutAcceptedListener::class,
    ],
    PayoutCreated::class => [
        PayoutCreatedListener::class,
    ],
    PayoutNotified::class => [
        PayoutNotifiedListener::class,
    ],
];

1. 命令 gigapay:webhook：laravel-gigapay 提供了一个命令，该命令将使用 APP_URL 注册所有 Webhooks，并且它还有一个接收这些 Webhooks 并触发事件的路由。所以一旦您使用 artisan 运行此命令，您的 Webhooks 就会被注册。

php artisan gigapay:webhook

• 完成这些步骤后，您的 Gigapay Webhooks 已设置完毕。现在，您只需添加可以监听这些 Webhook 事件的监听器即可。

• 下面是一个监听 Employee.created 事件的监听器示例。

<?php

namespace App\Listeners;

use Mazimez\Gigapay\Events\EmployeeCreated;
use Monolog\Logger;
use Monolog\Handler\StreamHandler;

class EmployeeCreatedListener
{
    /**
     * Create the event listener.
     *
     * @return void
     */
    public function __construct()
    {
        //
    }

    /**
     * Handle the event.
     *
     * @param  EmployeeCreated  $event
     * @return void
     */
    public function handle(EmployeeCreated $event)
    {
        //stuff you can do with this event resource to update you system 
        $employee = $event->getResource();

        //logging data just as an example
        $logger = new Logger('gigapay-webhooks-logs');
        $logger->pushHandler(new StreamHandler(storage_path('logs/gigapay/gigapay-webhooks-logs.log')));
        $logger->info('employee created with id of ' . $employee->id);
    }
}

• 在上面的示例中，EmployeeCreatedListener 在其 handle 方法中监听 EmployeeCreated 事件。
• 在 handle 方法中，您将获取 EmployeeCreated 事件的实例，您可以在其中调用 getResource 方法，该方法将给出与该事件相关的资源。
• getResource 方法可以根据事件返回不同的资源，可以是 Employee、Payout 或 Invoice。
• 一旦您获取了资源，就可以使用它来更新您的系统。
• 由于总共有9个 Webhooks，因此总共有9个不同的事件。您可以从 gigapay.php 的配置文件中的 events_list 获取这些事件列表。
• 您必须创建9个不同的监听器，就像上面一样，来处理不同的 Webhook 事件。

webhook-list

Webhook::list 方法将返回 Webhooks 的 ListResource，您可以使用它来应用筛选器和搜索所有 Webhooks。您可以从Gigapay 文档获取更多信息。

use Mazimez\Gigapay\Webhook;

$webhooks = Webhook::list(); //getting list of webhooks
$webhooks = $webhooks->paginate(1, 5);  //add pagination
return $webhooks->getJson();

webhook-creation

• 如果您想以其他方式配置 Gigapay Webhooks 而不是使用 Laravel 事件，那么您也可以像处理其他资源一样使用 create 和 createByArray 方法。
• 在创建 Webhooks 时，只需要 url 和 events 字段。

use Mazimez\Gigapay\Webhook;

//creating webhook with create method
$webhook = Webhook::create(
    "https://youwebsite.url/webhooks",  //the url on which the webhook will send data
    "Employee.created",  //name of event
    null,  //secret_key
    json_encode(["date" => "data from your system"]),//json encoded data
    null, //unique id
);
return $webhook->getJson();


//creating webhook with createByArray method(only required parameters)
$webhook = Webhook::createByArray([
    "url" => "https://youwebsite.url/webhooks",
    "events" => "Employee.created",
]);
return $webhook->getJson();

webhook-retrieve

您可以通过其 id 检索任何 Webhook。您可以从Gigapay 文档获取更多信息。

use Mazimez\Gigapay\Webhook;

$webhook = Webhook::findById('1'); //getting webhook by it's id
return $webhook->getJson();

webhook-update

• Webhook 资源可以在任何时候更新，可以更新的数据包括 id、url、event、metadata、secret_key。
• 可以通过调用单独的方法或通过在员工对象上更新值然后调用 save() 方法来更新每个数据，以更新整个员工对象。
• 请记住在保存元数据之前使用 json_encode()。
• 记住，事件在保存时应该是字符串，而不是数组。
• 另外，要更新员工的ID，请使用单独的方法 updateId() 而不是 save()，因为 save() 会尝试更新具有当前ID的webhook（该ID在 Gigapay 数据库中不存在）。
• 关于唯一性和格式的规则仍然适用。你可以从 Gigapay 文档 获取更多信息。

use Mazimez\Gigapay\Webhook;

//#1: updating values using separate methods
$webhook = Webhook::findById('webhook-id'); //finding webhook by id

$webhook = $webhook->updateId('new-webhook-id'); //updating id
$webhook = $webhook->updateUrl("https://youwebsite.new.url/webhooks"); //updating url
$webhook = $webhook->updateEvent("Payout.created"); //updating event
$webhook = $webhook->updateSecretKey("new-secret.key"); //updating secret-key
$webhook = $webhook->updateMetaDate(json_encode([
    "data" => "some more data from you system",  //updating metadata
]));
return $webhook->getJson();

//#2 updating values using save() methods
$webhook = Webhook::findById('webhook-id'); //finding webhook by id

$webhook->url  = "https://youwebsite.new.url/webhooks"; //updating url
$webhook->event = "Payout.created"; //updating event
$webhook->secret_key = "new-secret.key"; //secret-key
$webhook->metadata = json_encode([
    "data" => "some more data from you system", //updating metadata
]);
$webhook->save(); //saving the webhook object
return $webhook->getJson();

webhook-replace

与员工类似，webhook也可以被替换。这将更新webhook的ID。你可以从 Gigapay 文档 获取更多信息。

use Mazimez\Gigapay\Webhook;

$webhook = Webhook::findById('1'); //getting webhook by it's id
$webhook->replace([//replacing webhook with new data
    'url' => "https://jobmatchr.se/webhooks/"
]);
return $webhook->getJson();//returning new webhook instance

webhook-delete

您可以通过在Webhook实例上调用destroy方法来删除任何webhook。更多信息请参考 Gigapay 文档。

use Mazimez\Gigapay\Webhook;

$webhook = Webhook::findById('webhook-id'); //getting webhook by it's id
$webhook->destroy(); //deletes the webhook
return $webhooks->getJson(); //return the empty webhook instance

列表资源

这是一个提供从 Gigapay 获取任何资源列表的一些辅助方法的类。您可以使用的方法是

paginate

这将向 Gigapay API 添加分页参数。它需要两个参数，page 和 page_size。您可以直接在任意 ListResource 实例上链式调用此方法，您也可以参考 Gigapay 文档。

use Mazimez\Gigapay\Employee;

$employees = Employee::list();
$employees->paginate($page, $page_size);  //paginate methode with parameters
return $employees->getJson();

search

这将向 Gigapay API 添加搜索参数。它需要一个参数，search。您可以直接在任意 ListResource 实例上链式调用此方法。

use Mazimez\Gigapay\Employee;

$employees = Employee::list();
$employees->search('test');  //chaining search methode 
return $employees->getJson();

expand

这将添加用于扩展任何资源的参数，例如，一个 Payout 有一个关联的员工标识符。那些对象可以被扩展

use Mazimez\Gigapay\Payout;

$payouts = Payout::list();
$payouts->expand('employee'); //exapanding employee resource
return $payouts->getJson();

您也可以通过链式调用 expand 方法来扩展多个资源。您也可以参考 Gigapay 文档。

use Mazimez\Gigapay\Payout;

$payouts = Payout::list();
//exapanding employee and invoice resource
$payouts->expand('employee')->expand('invoice'); 
return $payouts->getJson();

addFilter

这将添加关于时间戳或关系过滤的过滤参数。您只需添加后缀如 _before 或 _after。您也可以参考 Gigapay 文档。请注意，这里所有的时间戳都是以 ISO 8601 字符串的形式。您也可以链式调用此方法并添加多个过滤器

use Mazimez\Gigapay\Employee;

$employees = Employee::list();

//adding filter to get the employees who are created before 10 days
$employees->addFilter('created_at_before', Carbon::now()->subDays(10)->toISOString());

//adding filter to get the onty verfied employees.
$invoice->addFilter('verified_at_null', 'false');

return $invoice->getJson();

getJson

这将返回应用了所有过滤器后从 Gigapay API 获取的 JSON 响应。

use Mazimez\Gigapay\Employee;

$employees = Employee::list();
return $invoice->getJson(); //returning json response

异常处理

Gigapay 异常

• Laravel-Gigapay 还提供了一些辅助方法来处理 Gigapay API 返回的错误和异常。
• 当 Gigapay API 返回任何错误时，它将以 GigapayException 的形式抛出，您可以 catch 它并适当地显示错误
• Gigapay 通常以 json 格式返回错误，包括字段名和与该字段相关的错误。
• 有关该错误的 json 数据可以通过在 GigapayException 实例上调用 getJson() 方法来显示。
• GigapayException 还提供了一个 getErrorMessage 方法，它将 json 转换为单条消息，您可以将其显示给最终用户。

use Mazimez\Gigapay\Exceptions\GigapayException;
use Mazimez\Gigapay\Invoice;

try {
    return Invoice::findById("non-exiting-id")->getJson(); //code that will surely gives error.
} catch (GigapayException $th) { //catching the error with GigapayException
    return [
        'message' => $th->getErrorMessage(), //the error message
        'json' => $th->getJson() //the json
    ];
} catch (Exception $th) {
    return $th->getMessage(); //catching exception other then GigapayException
}

• 结果

{
    "message": "Problem with detail->Not found.",
    "json": {
        "detail": "Not found."
    }
}