jeffersongoncalves / laravel-hubspot

1.0.0 2026-09-08 01:39 UTC

Requires

• php: ^8.2
• illuminate/http: ^12.0|^13.0
• illuminate/support: ^12.0|^13.0
• spatie/laravel-package-tools: ^1.16

Requires (Dev)

• larastan/larastan: ^3.0
• laravel/pint: ^1.21
• orchestra/testbench: ^10.0|^11.0
• pestphp/pest: ^3.0|^4.0
• pestphp/pest-plugin-laravel: ^3.0|^4.0

MIT

• Jefferson Gonçalves

• php
• composer
• crm
• laravel
• API-Client
• hubspot
• laravel-package

Published on Packagist.org on 2026-09-08 01:40 UTC

README

Laravel HubSpot

A PHP/Laravel client for the HubSpot API. Read and write any CRM object — contacts, companies, deals, tickets, custom objects — plus search, associations, form submissions, and marketing emails, authenticated with a private app token.

Features

• CRUD for any CRM object type (/crm/v3/objects/{type})
• Search: raw payloads or a one-line single-property filter
• Associations: create and read them between object types
• Form submissions (/form-integrations/v1) and marketing emails (/marketing/v3/emails)
• Automatic retry on 429, since HubSpot caps requests at 100 per 10 seconds
• Throws HubspotException (with the original API error body) on any non-2xx response

Installation

You can install the package via composer:

composer require jeffersongoncalves/laravel-hubspot

Publish the config file:

php artisan vendor:publish --tag=hubspot-config

Set your private app token in .env:

HUBSPOT_TOKEN=your-private-app-token

Create the token under Settings > Integrations > Private Apps and grant it the CRM scopes you need.

Configuration

// config/hubspot.php
return [
    'token' => env('HUBSPOT_TOKEN', ''),
    'base_url' => env('HUBSPOT_BASE_URL', 'https://api.hubapi.com'),
    'retry_times' => env('HUBSPOT_RETRY_TIMES', 3),
    'retry_delay' => env('HUBSPOT_RETRY_DELAY', 1000),
];

Usage

The package is resolved via the Hubspot facade or by injecting JeffersonGoncalves\Hubspot\Hubspot.

contacts(), companies(), deals() and tickets() are shortcuts for crm('contacts') and friends — use crm() directly for products, line_items, or a custom object.

List records

use JeffersonGoncalves\Hubspot\Facades\Hubspot;

$result = Hubspot::contacts()->all(['limit' => 10]);
// $result['results']

Find a record

$contact = Hubspot::contacts()->find('101', ['email', 'firstname', 'lastname']);
// $contact['properties']['email']

Create a record

$contact = Hubspot::contacts()->create([
    'email' => '[e-mail]',
    'firstname' => 'John',
    'lastname' => 'Doe',
    'company' => 'Example Inc',
]);
// $contact['id']

Update a record

Hubspot::contacts()->update('101', [
    'lifecyclestage' => 'customer',
]);

Delete a record

Hubspot::contacts()->delete('101');

Search

Single property, the common case:

$result = Hubspot::contacts()->searchBy('email', '[e-mail]', properties: ['email', 'firstname']);

Or pass the raw payload for anything more complex:

$result = Hubspot::deals()->search([
    'filterGroups' => [[
        'filters' => [
            ['propertyName' => 'dealstage', 'operator' => 'EQ', 'value' => 'appointmentscheduled'],
            ['propertyName' => 'amount', 'operator' => 'GT', 'value' => '5000'],
        ],
    ]],
    'sorts' => [['propertyName' => 'closedate', 'direction' => 'DESCENDING']],
    'limit' => 50,
]);

Deals

$deal = Hubspot::deals()->create([
    'dealname' => 'New Deal',
    'amount' => '10000',
    'dealstage' => 'appointmentscheduled',
    'pipeline' => 'default',
]);

Associations

Hubspot::deals()->associate($deal['id'], 'contacts', $contact['id'], 'deal_to_contact');

$contacts = Hubspot::deals()->associations($deal['id'], 'contacts');

Custom objects

$result = Hubspot::crm('p_subscriptions')->all();

Form submissions and marketing emails

$submissions = Hubspot::formSubmissions('form-guid');
$emails = Hubspot::marketingEmails(['limit' => 10]);

Error handling

Any non-2xx API response throws JeffersonGoncalves\Hubspot\Exceptions\HubspotException, which exposes the decoded error body:

use JeffersonGoncalves\Hubspot\Exceptions\HubspotException;

try {
    Hubspot::contacts()->find('unknown-id');
} catch (HubspotException $e) {
    logger()->error($e->getMessage(), $e->errorBody());
}

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email the author instead of using the issue tracker.

Credits

• Jefferson Gonçalves
• All Contributors

License

The MIT License (MIT). Please see License File for more information.