grnhse/greenhouse-tools-php

此包的最新版本（v2.2.0）没有提供许可证信息。

一个包含与Greenhouse职位板和API交互服务的PHP包。

维护者

详细信息

github.com/grnhse/greenhouse-tools-php

主页

源代码

问题

安装: 196,904

依赖项: 0

建议者: 0

安全: 0

星标: 23

关注者: 6

分支: 10

开放问题: 1

v2.2.0 2022-10-11 16:35 UTC

Requires

Requires (Dev)

Unknown License a7c60450cc5b923e94b1c2d65be973f9a809b373

  • Tom Phillips <tphillips.woop@greenhouse.io>

apijob boardgreenhouse

This package is not auto-updated.

Last update: 2024-09-18 08:13:57 UTC

README

此工具包由Greenhouse提供，供使用PHP的客户使用。提供了三个工具。

  1. 职位板服务：用于在模板或视图文件中嵌入iframe。
  2. 职位API服务：用于从Greenhouse职位板API获取数据。
  3. 申请服务：用于向Greenhouse发送申请。
  4. Harvest服务：用于与Harvest API交互。

需求

  1. PHP版本
    • V1需要5.6或更高版本。
    • V2需要7.3或更高版本。
  2. Composer。您应该使用Composer来管理此包。

由于PHP 5和Guzzle 6的EOL，此包已升级到需要PHP 7.3。我们将不再支持V1。从现在起，新功能将仅添加到2.0分支。您应尽快更新到2.0。

安装

此包可在Packagist上找到。通过Composer安装。将以下内容添加到您的需求中

    "grnhse/greenhouse-tools-php": "~2.0"

2.2新增功能

  • 从Guzzle 7.1到7.5的微小版本升级。
  • 增加了对v1以上Greenhouse端点版本的支持。

2.1新增功能

为了支持Greenhouse的新Inclusion URL，我们取消了某些URL中包含$id的要求。以前，像getActivityFeedForUser()这样的URL会抛出一个需要id的Greenhouse异常。现在，该方法将转换为user/activity_feed并返回404 Not Found响应。我们这样做是为了支持Greenhouse的新Inclusion URL。在上一版本中，getQuestionsSetsForDemographics()，(在此处找到)会抛出一个“需要id”的异常，而不是正确路由到demographics/question_sets。

2.0新增功能

为了支持Guzzle的最新版本，放弃了PHP 5.6、7.0、7.1和7.2的支持。

Greenhouse服务

Greenhouse服务是一个父级服务，返回其他Greenhouse服务。通过使用此服务，您可以访问所有其他服务。Greenhouse服务接受一个数组，该数组可选地包含您的职位板URL令牌(在Greenhouse中找到此处)和您的职位板API凭据(在Greenhouse中找到此处)。创建一个Greenhouse服务对象，如下所示

<?php

use \Greenhouse\GreenhouseToolsPhp\GreenhouseService;
	
$greenhouseService = new GreenhouseService([
	'apiKey' => '<your_api_key>', 
	'boardToken' => '<your_board_token>'
]);

?>

使用此服务，您可以轻松访问其他Greenhouse服务，并且它将根据需要使用板令牌和客户端令牌。

职位板服务

此服务生成适当的HTML标签，用于与Greenhouse iframe集成。使用此服务生成指向Greenhouse托管职位板的链接或适当的标签。通过调用以下内容访问职位板服务

<?php

$jobBoardService = $greenhouseService->getJobBoardService();

// Link to a Greenhouse hosted job board
$jobBoardService->linkToGreenhouseJobBoard();

// Link to a Greenhouse hosted job application
$jobBoardService->linkToGreenhouseJobApplication(12345, 'Apply to this job!', 'source_token');

// Embed a Greenhouse iframe in your page
$jobBoardService->embedGreenhouseJobBoard();

?>

职位API服务

使用此服务从我们的职位板API获取公共职位板信息。此服务无需API密钥。此服务用于与Greenhouse职位板API的GET端点交互。这些方法可以在这里找到。通过以下方式访问此服务：

$jobApiService = $greenhouseService->getJobApiService();

此服务中的方法名称与端点相关，因此要使用GET Offices端点，您会调用

$jobApiService->getOffices();

要获取特定的办公室

$jobApiService->getOffice($officeId);

在任何情况下使用的唯一附加参数是Jobs端点的"content"和"questions"参数。这些参数在getJobs和getJob方法中通过布尔参数管理，默认值为false。要获取包含内容的所有职位，您会调用

$jobApiService->getJobs(true);

而要获取包含问题的职位，您会调用

$jobApiService->getJob($jobId, true);

应用程序服务

使用此服务将申请发布到Greenhouse。使用此服务需要职位板API密钥，可以在Greenhouse中生成。以下是对此服务的示例用法：

<?php

$appService = $greenhouseService->getApplicationApiService();
$postParams = array(
	'id' => 82354,
	'first_name' => 'Johnny',
	'last_name' => 'Test',
	'email' => 'jt@example.com',
	'resume' => new \CURLFile('path/to/file.pdf', 'application/pdf', 'resume.pdf'),
	'question_12345' => 'The answer you seek',
	'question_123456' => array(12345, 23456, 34567)
);
$appService->postApplication($postParams);

?>

提交多选答案

应用程序将根据您的API密钥生成授权头，并将应用程序作为多部分表单发布。此参数数组遵循PHP约定，除了多选提交（提交具有相同名称的参数）的情况。虽然PHP文档希望用户像这样提交多个值：

'question_123456[0]' => 23456,
'question_123456[1]' => 12345,
'question_123456[2]' => 34567,

Greenhouse需要您这样做

'question_123456' => array(23456,12345,34567),

这可以防止由于Libcurl不使用数组索引命名约定而引起的问题。

Harvest服务

使用此服务与Greenhouse中的Harvest API交互。Harvest API文档可在此处找到。此服务旨在简化与Harvest API的交互。要创建Harvest服务对象，您必须提供有效的Harvest API密钥。请注意，这些与职位板API密钥不同。

<?php
  $harvestService = $greenhouseService->getHarvestService();
?>

通过Harvest服务，您可以与Greenhouse Harvest文档中概述的任何Harvest方法交互。Harvest URL大多符合以下五种格式之一

  1. https://harvest.greenhouse.io/v1/<object>：这是Greenhouse中GET方法的常见URL格式。对于此格式的端点，方法将类似于$harvestService->getObject()。示例包括$harvestService->getJobs()或$harvestService->getCandidates()
  2. https://harvest.greenhouse.io/v1/<object>/<object_id>：这将获取具有给定ID的对象。预期只会返回或操作一个对象。ID始终由一个具有键名id的参数数组提供。例如：$harvestService->getCandidate($parameters);
  3. https://harvest.greenhouse.io/v1/<object>/<object_id>/<sub_object>：此格式的URL通常意味着您想要获取具有对象ID的对象的所有子对象。示例包括$harvestService->getJobStagesForJob(array('id' => 123))和$harvestService->getOffersForApplication(array('id' => 123))
  4. https://harvest.greenhouse.io/v1/<object>/<object_id>/<sub_object>/<sub_object_id>：此格式的URL通常意味着您正在对单个子对象执行操作。一个示例是$harvestService->deleteTagsForCandidate(array('id' => 123, 'second_id' => 234))
  5. https://harvest.greenhouse.io/v1/<object>/<opbject_id>/<sub_object>/<qualifier>：此格式的URL通常意味着您正在尝试对一类子对象的有限范围进行操作。一个示例是$harvestService->deletePermissionForJobForUser(array('id' => 123));，这将从用户那里删除对职位的指定权限。

某些方法调用和URL不适用于此格式，但方法名称尽可能接近该格式。这些包括

您应使用参数数组提供任何harvest方法所需的URL参数和头信息。对于任何需要JSON主体的项目，这也会在参数数组中提供。

例如： 移动一个申请

$parameters = array(
    'id' => $applicationId,
    'headers' => array('On-Behalf-Of' => $auditUserId),
    'body' => '{"from_stage_id": 123, "to_stage_id": 234}'
);
$harvestService->moveApplication($parameters);

请注意，您不需要在headers数组中提供授权头信息。如果提供的API密钥有效，它将自动附加到headers数组中。

参数数组也用于提供任何分页和过滤选项，这些选项通常作为GET查询字符串提供。不在id、headers或body键中的任何内容都将假定是URL参数。

例如： 获取一页申请

$parameters = array(
    'per_page' => 100,
    'page' => 2
);
$harvestService->getApplications($parameters);
// Will call https://harvest.greenhouse.io/v1/applications?per_page=100&page=2

如果以任何方式提供了ID键，则它将优先。

例如： 将候选人添加到Greenhouse

关于分页的说明： 如Harvest文档中所述，Greenhouse根据端点支持两种分页方法。下一页包含在Link头中返回。下一页链接可在Harvest服务中访问

  $harvestService->nextLink();

此方法返回的链接将提供此端点的下一页对象。根据端点支持的分页方法，返回的链接将类似于以下之一

  • https://harvest.greenhouse.io/v1/<object>?page=2&per_page=100
  • https://harvest.greenhouse.io/v1/<object>/?since_id=161963

如果nextLink()方法返回空值，则表示已到达最后一页。

Greenhouse在Harvest中包含几个用于POST新对象的POST方法。需要注意的是，Harvest中候选人和应用程序的创建与上述应用程序服务不同。通过Harvest接收文档只能通过二进制内容或包含包含文档的URL来实现。因此，Harvest服务使用Guzzle中的body参数而不是包含POST参数。

$candidate = array(
    'first_name' => 'John',
    'last_name' => 'Doe',
    'phone_numbers' => array(
        array('value' => '310-555-2345', 'type' => 'other')
    ),
    'email_addresses' => array(
        array('value' => 'john.doe@example.com', 'type' => 'personal')
    ),
    'applications' => array(
        array(
            'job_id' => 146855,
            'attachments' => array(
                array(
                    'filename' => 'resume.pdf',
                    'type' => 'resume',
                    'url' => 'http://example.com/resume.pdf',
                    'content_type' => 'application/pdf'
                )
            )
        )
    )
);
$parameters = array(
    'headers' => array('On-Behalf-Of' => 12345),
    'body' => json_encode($candidate)
)
$harvest->postCandidate($parameters);

所有使用POST的Greenhouse Harvest方法都将遵循此约定。简而言之，JSON主体应根据Greenhouse提供的文档在body参数中发送。

关于自定义字段的说明： getCustomFields和getCustomField与Harvest服务的其他部分不同。getCustomFields接受一个文本id以限制响应仅包含特定对象集的自定义字段。例如，您可以使用id => 'job'来返回只有工作的自定义字段。而getCustomField则接受一个正常的数字id以检索单个自定义字段。

关于未来发展的说明： Harvest包利用PHP的魔术__call方法。这是为了处理Greenhouse的Harvest API超过此包。新的端点URL应该自动工作。如果Greenhouse添加了GET https://harvest.greenhouse.io/v1/widgets端点，调用$harvestService->getWidgets()应该由此包支持。

例： 删除应用程序

Greenhouse现在还支持通过API服务使用DELETE方法，这需要删除对象及其所属用户的id。

// DELETE an application
$parameters = array(
    'id' => $applicationId,
    'headers' => array('On-Behalf-Of' => $auditUserId)
);
$harvestService->deleteApplication($parameters);

所有通过Harvest进行的Greenhouse删除事件都将遵循此约定。

异常

Greenhouse服务库引发的全部异常都继承自GreenhouseException。捕获此异常可以捕获此库抛出的任何内容。