- How do I install fiveam-code/laravel-notion-api in a Laravel app?
- Install it with composer require fiveam-code/laravel-notion-api; the service provider and facade are auto-discovered, so no manual registration is needed on modern Laravel. Publish the config file with php artisan vendor:publish and add your NOTION_TOKEN to the .env file. Then create an internal integration in Notion and explicitly share the target pages or databases with it, because an unshared page is invisible to the API even with a valid token. A working read of one database is realistically a one to two day spike.
- Which Laravel and PHP versions does this package support?
- The package is a standard Laravel service-provider wrapper and targets PHP 8.x, but you should read the composer.json constraints before committing rather than assuming. Laravel majors move faster than many integration packages release, so the Laravel ceiling is the constraint to verify first. Pin the package to an exact minor version to avoid surprise transitive bumps, and confirm the support matrix matches your target app.
- How does authentication with Notion work in this package?
- You create an internal integration in Notion, copy the generated secret, and place it in your .env as NOTION_TOKEN so the package can send it as a bearer token on every request. Authentication alone is not enough: each page or database must be shared with the integration from the Notion UI, which is the most common cause of empty responses. That token is workspace-scoped, so treat it as a secret and keep it out of version control.
- How do I query a Notion database with the fluent interface?
- The package exposes an Eloquent-like query builder over Notion databases, so you can chain filters and sorts instead of hand-building the raw JSON request body. Results come back as page objects you can read properties from, and the same fluent surface covers creating and updating pages and blocks. It is a thin abstraction over the official notion-sdk-php, so behavior maps closely to the underlying Notion API semantics.
- Does this package handle Notion pagination and rate limits for me?
- No, and it cannot, because those are structural properties of the Notion API rather than wrapper limitations. Notion caps results at 100 records per response and enforces a rate limit of roughly three requests per second sustained. You still need to follow the next_cursor until it is exhausted, and for bulk syncs you should push work onto queued jobs with throttling so you do not silently truncate data or get 429 responses. Plan for this in your repository layer rather than assuming the package abstracts it away.
- Can I access the raw notion-sdk-php client when the fluent API is missing a feature?
- Yes, the package is deliberately a thin wrapper over the official notion-sdk-php, so dropping to the underlying client is the intended escape hatch when the fluent API lags a new Notion capability. Confirm the exact accessor in the README during your spike, but architecturally this is what makes the dependency low-commitment and replaceable. Keeping raw SDK access available means you are never blocked waiting on a wrapper release.
- How do I test a Notion integration without hitting the real API in CI?
- The package ships with testing fakes, so you can swap the facade for a fake and assert the requests your application would have sent without any network calls. This keeps CI deterministic and avoids burning rate limit quota or requiring a live token in the pipeline. Because Notion is an external system, an HTTP fake strategy is the right default; reserve real calls for a small number of manual or nightly smoke tests.
- Which Notion API version does this package pin, and does it support the 2025-09 data source change?
- The package sends a Notion-Version header inherited from the bundled notion-sdk-php, and you should check exactly which version it pins before adopting it. Notion's 2025-09 data-source split materially reworked database query semantics, so a version mismatch is the most likely blocker in a new integration. Confirm whether the header is overridable per request and whether the data-source model is supported. Treat the Notion API version as a pinned dependency with an owner and a review date.
- Should I use Notion as my application's primary database through this package?
- No. Use it where Notion is the editorial or back-office system of record and Laravel is the delivery tier: marketing content, docs, internal tooling, and lightweight CMS use cases. Notion's rate limits, 100-record pagination ceiling, and three-level block nesting limit are structural constraints that make it unsuitable as primary persistence. For anything load-bearing, put the package behind an internal repository interface so you can swap implementations or absorb API changes without a rewrite.
- Is fiveam-code/laravel-notion-api actively maintained, and what happens if it is abandoned?
- It is maintained by a small team at 5am-code, so the bus factor is roughly one and you should corroborate health with Packagist download stats and recent issue-close velocity rather than download counts alone. The MIT license plus the thin-wrapper design means forking or replacing it is genuinely viable, which is what keeps the risk medium rather than high. Mitigate further by pinning an exact version and keeping your integration behind an interface so the wrapper is never load-bearing.