README

Modern PHP SDK for the Careerjet job search API.
Provides a type-safe, PSR-4 compliant client with Guzzle HTTP transport, strict types, and full IDE autocompletion.

Installation

composer require resumegoonline/careerjet-sdk

Requires PHP 8.1+ and ext-json.

Quick Start

use ResumeGoOnline\CareerjetSdk\CareerjetClient;
use ResumeGoOnline\CareerjetSdk\Dto\Request\SearchQuery;
use ResumeGoOnline\CareerjetSdk\Dto\Request\SortType;

$client = new CareerjetClient('<YOUR_API_KEY>');

$result = $client->search(new SearchQuery(
    localeCode: 'en_GB',
    keywords: 'php developer',
    location: 'London',
    page: 1,
    pageSize: 10,
    sort: SortType::Relevance,
));

if ($result->isJobs()) {
    echo "Found {$result->hits} jobs ({$result->pages} pages)\n";
    echo "Response time: {$result->responseTime}s\n";

    foreach ($result->jobs as $job) {
        echo "{$job->title} at {$job->company} — {$job->locations}\n";
        echo "  {$job->salary} ({$job->salaryCurrencyCode})\n";
        echo "  {$job->url}\n\n";
    }
} elseif ($result->isLocations()) {
    echo "{$result->message}\n";
    foreach ($result->locations as $location) {
        echo "  — {$location->name}\n";
    }
}

Note: You need a Careerjet API key — register at careerjet.com/partners.

Authentication

The SDK uses HTTP Basic authentication. Your API key is sent as the username with an empty password in the Authorization header:

Authorization: Basic base64(API_KEY:)

API Reference

`CareerjetClient`

public function __construct(
    string $apiKey,
    ?HttpClientInterface $httpClient = null,
)

Parameter	Type	Description
`$apiKey`	`string`	Your Careerjet API key (required).
`$httpClient`	`?HttpClientInterface`	Custom HTTP transport. Uses Guzzle 7 with 10s timeout by default.

public function search(
    SearchQuery $query,
    ?string $userIp = null,
    ?string $userAgent = null,
    ?string $referer = null,
): SearchResult

Parameter	Type	Description
`$query`	`SearchQuery`	Search parameters (required).
`$userIp`	`?string`	Client IP address. Auto-detected from `$_SERVER` headers if `null`.
`$userAgent`	`?string`	Client User-Agent. Auto-detected from `$_SERVER` if `null`.
`$referer`	`?string`	Referer URL. Auto-detected from `$_SERVER` if `null`.

⚠️ user_ip and user_agent are required by the Careerjet API. The SDK will throw a CareerjetApiException if neither auto-detection nor explicit values are available (e.g. in CLI scripts).

`SearchQuery` DTO

new SearchQuery(
    keywords: 'php developer',
    location: 'London',
    localeCode: 'en_GB',
    sort: SortType::Relevance,
    page: 1,
    pageSize: 20,
    offset: 0,
    fragmentSize: 120,
    radius: 5,
    contractType: ContractType::Permanent,
    workHours: WorkHours::FullTime,
)

Field	Type	Default	API Param	Description
`keywords`	`string`	`''`	`keywords`	Search terms (space-separated).
`location`	`string`	`''`	`location`	Location. Empty = country-wide.
`localeCode`	`string`	`'en_US'`	`locale_code`	`[lang]_[COUNTRY]` format (see locales below).
`sort`	`SortType`	`Relevance`	`sort`	Sort order.
`page`	`int`	`0`	`page`	Page number (1–10). Overrides `offset` when > 0.
`pageSize`	`int`	`20`	`page_size`	Results per page (1–100).
`offset`	`int`	`0`	`offset`	Zero-based offset (0–999). Ignored if `page` > 0.
`fragmentSize`	`int`	`120`	`fragment_size`	Description excerpt size in characters.
`radius`	`int`	`5`	`radius`	Search radius in km/miles.
`contractType`	`?ContractType`	`null`	`contract_type`	Contract type filter.
`workHours`	`?WorkHours`	`null`	`work_hours`	Working hours filter.

Enums

`SortType`

Case	Value	Description
`Relevance`	`relevance`	Sort by decreasing relevance.
`Date`	`date`	Sort by decreasing date.
`Salary`	`salary`	Sort by decreasing salary.

`ContractType`

Case	Value	Description
`Permanent`	`p`	Permanent position.
`Contract`	`c`	Contract position.
`Temporary`	`t`	Temporary position.
`Internship`	`i`	Internship / training.
`Volunteering`	`v`	Volunteering position.

`WorkHours`

Case	Value	Description
`FullTime`	`f`	Full-time position.
`PartTime`	`p`	Part-time position.

`SearchResult` DTO

Field	Type	Description
`type`	`string`	`'JOBS'` or `'LOCATIONS'`.
`message`	`string`	Human-readable message from the API.
`responseTime`	`float`	API response time in seconds (e.g. `0.322`).
`hits`	`int`	Total number of matching jobs (JOBS type only).
`pages`	`int`	Total number of result pages (JOBS type only).
`jobs`	`Job[]`	List of job offers.
`locations`	`Location[]`	List of suggested locations (when original location was ambiguous).
`rawData`	`array`	Full raw API response for forward-compatibility.

Helper methods:

$result->isJobs(): bool — true when type === 'JOBS'.
$result->isLocations(): bool — true when type === 'LOCATIONS'.

`Job` DTO

Field	Type	Description
`url`	`string`	Job offer URL (via jobviewtrack.com redirect).
`title`	`string`	Job title.
`description`	`string`	Job description excerpt (may contain HTML).
`company`	`string`	Company name.
`locations`	`string`	Location string (e.g. `"London"`).
`date`	`string`	Publication date (e.g. `"Wed, 15 Nov 2025 19:13:43 GMT"`).
`salary`	`string`	Formatted salary (e.g. `"$30,000 - 33,000"`).
`salaryCurrencyCode`	`string`	ISO currency code (e.g. `"USD"`).
`salaryMin`	`?float`	Minimum salary value, or `null`.
`salaryMax`	`?float`	Maximum salary value, or `null`.
`salaryType`	`string`	`'Y'` = yearly, `'M'` = monthly, `'W'` = weekly, `'D'` = daily, `'H'` = hourly.
`site`	`string`	Source site domain (e.g. `"domain.com"`).
`rawData`	`array`	All raw API fields.

`Location` DTO

Field	Type	Description
`name`	`string`	Location name (e.g. `"London (Greater London)"`).
`rawData`	`array`	All raw API fields.

Casts to string via __toString().

Error Handling

All SDK errors extend ResumeGoOnline\CareerjetSdk\Exception\CareerjetException (which extends \RuntimeException).

CareerjetApiException is thrown on:

API returns type: "ERROR" response
Missing required user_ip or user_agent
Invalid JSON response body

Access the original API error details:

try {
    $result = $client->search($query);
} catch (CareerjetApiException $e) {
    echo $e->getMessage();         // Human-readable
    echo $e->getApiErrorType();    // e.g. "MISSING_PARAM"
    echo $e->getApiErrorMessage(); // Original API message
}

Supported Locales

Code	Language	Country
`cs_CZ`	Czech	Czech Republic
`da_DK`	Danish	Denmark
`de_AT`	German	Austria
`de_CH`	German	Switzerland
`de_DE`	German	Germany
`en_AE`	English	United Arab Emirates
`en_AU`	English	Australia
`en_CA`	English	Canada
`en_CN`	English	China
`en_GB`	English	United Kingdom
`en_HK`	English	Hong Kong
`en_IE`	English	Ireland
`en_IN`	English	India
`en_MY`	English	Malaysia
`en_NZ`	English	New Zealand
`en_OM`	English	Oman
`en_PH`	English	Philippines
`en_PK`	English	Pakistan
`en_QA`	English	Qatar
`en_SG`	English	Singapore
`en_TW`	English	Taiwan
`en_US`	English	United States
`en_VN`	English	Vietnam
`en_ZA`	English	South Africa
`es_AR`	Spanish	Argentina
`es_BO`	Spanish	Bolivia
`es_CL`	Spanish	Chile
`es_CR`	Spanish	Costa Rica
`es_DO`	Spanish	Dominican Republic
`es_EC`	Spanish	Ecuador
`es_ES`	Spanish	Spain
`es_GT`	Spanish	Guatemala
`es_MX`	Spanish	Mexico
`es_PA`	Spanish	Panama
`es_PE`	Spanish	Peru
`es_PR`	Spanish	Puerto Rico
`es_PY`	Spanish	Paraguay
`es_UY`	Spanish	Uruguay
`es_VE`	Spanish	Venezuela
`fi_FI`	Finnish	Finland
`fr_BE`	French	Belgium
`fr_CA`	French	Canada
`fr_CH`	French	Switzerland
`fr_FR`	French	France
`fr_LU`	French	Luxembourg
`fr_MA`	French	Morocco
`hu_HU`	Hungarian	Hungary
`it_IT`	Italian	Italy
`ja_JP`	Japanese	Japan
`ko_KR`	Korean	Korea
`nl_BE`	Dutch	Belgium
`nl_NL`	Dutch	Netherlands
`no_NO`	Norwegian	Norway
`pl_PL`	Polish	Poland
`pt_BR`	Portuguese	Brazil
`pt_PT`	Portuguese	Portugal
`ru_RU`	Russian	Russia
`ru_UA`	Russian	Ukraine
`sk_SK`	Slovak	Slovakia
`sv_SE`	Swedish	Sweden
`tr_TR`	Turkish	Turkey
`uk_UA`	Ukrainian	Ukraine
`vi_VN`	Vietnamese	Vietnam
`zh_CN`	Chinese	China

Custom HTTP Client

The SDK ships with a Guzzle 7 implementation. You can swap it out via the HttpClientInterface:

use ResumeGoOnline\CareerjetSdk\HttpClient\HttpClientInterface;

class MyHttpClient implements HttpClientInterface
{
    public function get(string $url, array $headers = []): string
    {
        // Your custom logic
    }
}

$client = new CareerjetClient('API_KEY', new MyHttpClient());

Useful for testing with mocks, adding logging middleware, or using a different HTTP library.

Testing

composer install
vendor/bin/phpunit

PHPUnit 10.5.64
............................  28 / 28 (100%)
OK (28 tests, 142 assertions)

Test suite covers:

SearchQuery — defaults, page/offset logic, contract/work hours filters
Job — full, partial and empty fromArray() parsing
Location — various input formats, __toString()
SearchResult — JOBS, LOCATIONS, empty locations, ERROR → exception, unknown types
CareerjetClient — constructor validation, successful search, error responses, missing required params, HTTP headers

License

MIT. See LICENSE for details.

resumegoonline / careerjet-sdk

Maintainers

Package info

Statistics

Security

README

Installation

Quick Start

Authentication

API Reference

`CareerjetClient`

`SearchQuery` DTO

Enums

`SortType`

`ContractType`

`WorkHours`

`SearchResult` DTO

`Job` DTO

`Location` DTO

Error Handling

Supported Locales

Custom HTTP Client

Testing

License

resumegoonline / careerjet-sdk

Maintainers

Package info

Statistics

Security

README

Installation

Quick Start

Authentication

API Reference

CareerjetClient

SearchQuery DTO

Enums

SortType

ContractType

WorkHours

SearchResult DTO

Job DTO

Location DTO

Error Handling

Supported Locales

Custom HTTP Client

Testing

License

`CareerjetClient`

`SearchQuery` DTO

`SortType`

`ContractType`

`WorkHours`

`SearchResult` DTO

`Job` DTO

`Location` DTO