Laravel Patrowl Laravel Package

Technical Evaluation

Architecture fit: This package is a Patrowl API client/SDK for Laravel/PHP applications, exposing service accessors such as organizations(), assets(), assetTags(), and now controls() plus read-only EASM resources. It fits applications that need to surface security posture, asset inventory, control impact, or EASM exposure data. v2.0.0 improves portability by removing DTO reads of Laravel’s config(), so the package can work outside Laravel and no longer overrides the connector’s default organization. That is a meaningful architectural improvement for mixed PHP/Laravel estates.

Integration feasibility: Feasible but not drop-in. This is a major release with breaking changes, so existing integrations need a deliberate upgrade. The most impactful changes are removed methods (organizations()->default(), assets()->replace(), assetTags()->all(), assetTags()->get()), a return-type change for organizations()->all(), a new exception path for assets()->create() on HTTP 208, and stricter DTO shapes such as non-nullable CreateAssetGroupData::$criticality and array-typed AssetInListData::$relatedTechnologies. New EASM read-only coverage, control asset listing, and asset move capabilities add product value but increase the integration surface.

Technical risk: High for existing consumers because the release is explicitly breaking. Risks include runtime/type errors from changed DTO returns, code paths that still call removed methods, unhandled AssetAlreadyExistsException, and assumptions that asset tags can still be fetched directly. The removal of assetTags()->all() and get() reflects upstream API removal, so there is no package-level workaround unless tags are obtained through other asset/control payloads. assets()->move() also carries workflow risk because it recreates an asset in another organization and deletes the source unless deleteSource: false; owners, teams, and groups are not copied. Backend compatibility must be confirmed against Patrowl API 2.36–2.38.

Key questions:

• Which removed methods and changed DTO fields are currently used in our codebase?
• Is UPGRADE.md sufficient for each breaking change, especially the replacement path for assets()->replace() and organizations()->default()?
• Which Patrowl API versions will production use, and are 2.36–2.38 available in all environments?
• Do we need EASM read-only data in this release, or can EASM integration follow the compatibility upgrade?
• How should AssetAlreadyExistsException be handled: treat as idempotent success, reconcile existing asset, or fail the workflow?
• What are the expected data volumes and pagination limits for EASM and controls()->assets($controlId)?
• Is assets()->move() acceptable operationally given that ownership/team/group metadata is not copied?
• What PHP and Laravel versions are supported, and does the package now officially support non-Laravel usage?

Integration Approach

Stack fit: Good fit for Laravel/PHP services that already use Patrowl or plan to expose Patrowl asset, control, and EASM data. The reduced Laravel coupling is positive for queue workers, CLI jobs, and non-Laravel PHP services. Teams should treat it as an SDK upgrade, not a routine dependency bump.

Migration path: Create an upgrade branch and inventory all calls to the removed and changed APIs. Replace organizations()->default() usage with explicit organization selection from configuration or domain data. Update organizations()->all() consumers to expect an array of OrganizationLiteData. Remove or redesign any assetTags()->all()/get() flows. Add explicit handling for AssetAlreadyExistsException around assets()->create(). Update CreateAssetGroupData construction to always provide criticality, and update consumers of AssetInListData::$relatedTechnologies to handle arrays. Follow UPGRADE.md for any remaining replacement patterns, especially for assets()->replace().

Compatibility: Confirm the Patrowl API version in each environment before deployment. The package targets API 2.36–2.38; older API versions may not support new controls, EASM, or corrected asset endpoints. Confirm PHP/Laravel version support and whether the package is now intended for standalone PHP use. Check that authentication and connector configuration still behave as expected after the removal of DTO-level config() reads.

Sequencing:

1. Pin the current package version and establish a rollback point.
2. Run static analysis and search for all removed methods, changed DTO properties, and assetTags() usage.
3. Upgrade the package in a branch and resolve compile/static-analysis failures.
4. Update tests for changed return types, exception handling, and non-nullable criticality.
5. Validate core asset and organization flows against a Patrowl 2.36–2.38 sandbox.
6. Add EASM read-only integration behind a feature flag if the data is not immediately required.
7. Integrate controls()->assets() and verify pagination behavior.
8. Pilot assets()->move() only after confirming metadata-loss and deletion behavior.
9. Deploy with monitoring for 208 responses, 403/404 errors, and move failures.

Operational Impact

Maintenance: This release creates a one-time major-upgrade maintenance burden and establishes a tighter dependency on Patrowl API versioning. The package is tracking upstream API changes, including removed endpoints, so future API changes may again require breaking package releases. Teams should budget for periodic compatibility reviews and keep UPGRADE.md in the upgrade checklist.

Support: Support risk is moderate to high during the upgrade because several changes are not simple renames. The removal of assetTags()->all()/get() has no obvious package-level substitute, and assets()->replace() is removed without a direct replacement stated in the release notes. Confirm vendor/community support response times and whether UPGRADE.md documents migration examples for each removed method. Internal runbooks should cover organization selection, 208 handling, and asset move recovery.

Scaling: EASM read-only resources may produce large result sets across domains, IPs, services, certificates, technologies, and CVEs. Plan pagination, caching, and job batching rather than loading full inventories synchronously. controls()->assets($controlId) has auto-pagination, which helps, but callers still need bounded page sizes and timeouts. assets()->move() is inherently heavier than an in-place update because it recreates and deletes assets, so avoid bulk moves without throttling and idempotency checks.

Failure modes:

• Calls to removed methods fail at runtime or static analysis.
• Consumers expecting a non-array from organizations()->all() break.
• assets()->create() raises AssetAlreadyExistsException on HTTP 208 if not handled.
• assetTags()->all()/get() fail because the API endpoints no longer exist.
• CreateAssetGroupData construction fails or sends invalid data when criticality is null.
• Code treating relatedTechnologies as a non-array breaks.
• assets()->move() partially completes, leaving duplicate assets or deleting a source before the target is fully usable.
• Moves lose owners, teams, and groups because those are not copied.
• Old asset delete/tag endpoints return 403/404 if any code bypasses the fixed package methods.
• DTO-level configuration assumptions break in non-Laravel workers, though this release should reduce that risk.

Ramp-up: Moderate. Developers need familiarity with Patrowl’s asset, organization, control, tag, and EASM data models, plus the new exception and DTO contracts. Allocate time for reading UPGRADE.md, reviewing the new examples (controls_assets_list.php, controls_warning_by_organization.php, assets_move.php), and writing migration tests. Teams without prior Patrowl experience should start with read-only EASM and control asset listing before attempting asset moves.