Download the PHP package blashbrook/papiclient without Composer

PAPIClient

A Laravel package for integrating with Polaris API (PAPI) services. Provides API client functionality and pre-built Livewire components for common library operations.

Key Features:

• Fluent API client for Polaris ILS integration
• Pre-built Livewire components (Delivery Options, etc.)
• Session management and user preference handling
• Comprehensive testing suite

Take a look at contributing.md to see a to do list.

Table of Contents

• Installation
• Usage
• Components
  • DeliveryOptionSelectFlux
  • Features
  • Configuration
  • Usage Examples
  • Troubleshooting
  • PatronUDFSelectFlux
  • PostalCodeSelectFlux
• Change log
• Testing
• Contributing
• License

Installation

Via Composer

Add the following variables to the project .env file

Usage

• Use Injection to instantiate PAPIClient in a class: `

• In a Livewire component, use the boot method:

• To make an API call to your Polaris server: `
• functions include:
  • method('GET|PUT')
  • protected() // Uses the protected API base URI instead of the default public URI.
  • patron('BARCODE') // Allows you to insert a patron's barcode into the URI.
  • uri('API Endpoint') // The part of the URI that performs the desired function (i.e 'authenicator/patron' or 'apikeyvalidate').
  • params(array) // Used for form submissions (i.e. ['Barcode'=>'55555555555555', 'Password'=> '1234'] is sent to log in a patron).
  • auth('AccessSecret') // Inserts a patron's temporary authentication token in the request headers.
  • MORE TO COME!

Components

DeliveryOptionSelectFlux

A Livewire component that provides a filtered, customizable select dropdown for delivery options using the Flux UI framework.

Features

• Filtered Options: Only displays allowed delivery options from your database
• Custom Display Names: Override database values with user-friendly labels
• Session Integration: Remembers user's selection across page visits
• Flux UI Integration: Seamlessly works with Flux select components
• Two-way Data Binding: Integrates with parent Livewire components via wire:model

Quick Start

To use the delivery options component with session integration:

1. In your Livewire component:

2. In your Blade template:

That's it! The component will show: Mail, Email, Phone, Text Messaging with session persistence.

Important: The component includes an updatedDeliveryOptionIDChanged() listener that automatically:

• Updates the session with the new selection
• Dispatches a deliveryOptionUpdated event to notify parent components

Configuration

1. Available Delivery Options

The component filters delivery options using an internal array. To modify which options are shown and their display names, edit the $availableDeliveryOptions array in /src/Livewire/DeliveryOptionSelectFlux.php:

Key Points:

• Database values (keys) must exactly match the DeliveryOption field in your database
• Display names (values) are what users see in the dropdown
• Only options listed in this array will appear in the select dropdown
• Any delivery options in your database NOT in this array will be filtered out

2. Usage in Blade Templates

Basic Usage:

With Initial Value:

3. Parent Component Integration

In your parent Livewire component:

4. Database Requirements

Ensure your delivery_options table has the structure:

Sample Data:

5. Customization Examples

Adding New Options:

1. Add the option to your database
2. Add it to the $availableDeliveryOptions array:

Changing Display Names:

Removing Options: Simply remove the line from the $availableDeliveryOptions array. The option will be filtered out even if it exists in the database.

6. Session Integration

The component automatically integrates with Laravel sessions:

• Reading: Gets initial value from session('DeliveryOptionID', defaultValue)
• Writing: Updates session when user changes selection (if parent component implements updatedDeliveryOptionIDChanged())
• Persistence: User's choice persists across browser sessions

7. Testing

The component includes comprehensive tests. Run them with:

8. Troubleshooting

Component not showing options:

• Verify database has delivery options with exact names matching $availableDeliveryOptions keys
• Check that the DeliveryOption model is accessible
• Ensure database connection is working

Trim error:

• This should be resolved, but if it occurs, clear view cache: php artisan view:clear

Session not persisting:

• Ensure updatedDeliveryOptionIDChanged() method is implemented in parent component
• Verify Laravel session configuration is correct

PatronUDFSelectFlux

A dynamic Livewire component that creates select dropdowns from Patron User Defined Fields (UDFs) stored in your database. Perfect for forms that need library-specific custom fields like School, Department, Grade Level, etc.

Features

• Dynamic UDF Loading: Automatically loads options from PatronUdf database records
• External Label Selection: Specify which UDF to use via the patronUdfLabel parameter
• Session Integration: Remembers user's selection with label-specific session keys
• Flux UI Integration: Modern, accessible UI components
• Custom Display Names: Override database values with user-friendly labels
• Event Broadcasting: Notifies parent components of selection changes
• Automatic Listener: Includes updatedSelectedPatronUDFChanged() for external variable updates

Quick Start

To use the PatronUDF component for a "School" selection:

1. In your Livewire component:

2. In your Blade template:

Important: The component includes an updatedSelectedPatronUDFChanged() listener that automatically:

• Updates the label-specific session (PatronUDF_School, etc.)
• Dispatches a patronUdfUpdated event to notify parent components
• Supports two-way data binding with external variables

PostalCodeSelectFlux

A comprehensive Livewire component for postal code selection with city, state, and county information. Ideal for address forms, service area selection, and location-based features.

Features

• Rich Location Data: Shows city, state, postal code, and county information
• Multiple Display Formats: Customizable display formats (full, city_state_zip, city_zip, etc.)
• Geographic Filtering: Filter by state, county, or other geographic criteria
• Session Integration: Remembers user's postal code selection
• Flux UI Integration: Modern, accessible select component
• Event Broadcasting: Dispatches detailed postal code information
• Search Functionality: Built-in search and filtering capabilities
• Automatic Listener: Includes updatedSelectedPostalCodeChanged() for external variable updates

Quick Start

To use the postal code component for address selection:

1. In your Livewire component:

2. In your Blade template:

Important: The component includes an updatedSelectedPostalCodeChanged() listener that automatically:

• Updates the session with the new postal code ID
• Dispatches a comprehensive postalCodeUpdated event with all location data
• Supports two-way data binding with external variables

Listener Implementation Details

All Flux components include automatic listeners that:

• Update external variables when selections change (enabling wire:model binding)
• Persist selections in session storage
• Dispatch events to notify parent components
• Handle empty/null values gracefully
• Support real-time updates without page refresh

Example of listener in action:

For complete configuration and usage examples, see the comprehensive testing documentation below.

Change log

PAPIClient has been refactored to use fluency! Now you can chain commands together, making the client more flexible and easier to use.

Please see the changelog for more information on what has changed recently.

@TODO Add Error catching

Testing

PAPIClient includes a comprehensive test suite covering unit tests, integration tests, and performance tests. The package uses PHPUnit 10 with organized test suites and convenient make commands.

Quick Start

Test Suites

Unit Tests

Fast, isolated tests that don't make real API calls:

Unit tests cover:

• PAPIClient instantiation and configuration
• Method chaining and fluent interface
• HTTP request building
• Response handling and error management
• Internal state management
• Mock API responses

Integration Tests

Tests that make real API calls to your PAPI server:

Integration tests cover:

• Real API connectivity
• Authentication flows
• Error handling with live API responses
• Network timeout scenarios
• Different HTTP methods

Prerequisites for Integration Tests: Set these environment variables before running integration tests:

Or use the setup helper:

Feature Tests

High-level tests for Laravel integration:

Performance Tests

Benchmark tests for response times and memory usage:

Coverage Reports

Generate detailed code coverage reports:

Make Commands Reference

All available testing commands via Makefile:

Direct PHPUnit Usage

If you prefer using PHPUnit directly:

Continuous Integration

For CI/CD pipelines, use:

Testing Configuration

The test suite uses phpunit.xml with separate configurations for:

• Test environment variables
• Database settings (using array drivers for speed)
• Source code coverage filtering
• Test suite organization

Test Safety

Important: Integration tests are disabled by default to prevent accidental API calls. They only run when explicitly enabled via environment variables.

• ✅ Unit tests: Always safe to run (no network calls)
• ✅ Feature tests: Safe (use Laravel testing features)
• ⚠️ Integration tests: Require real API credentials
• ✅ Performance tests: Safe (use mocked responses)

Component Testing

The package includes comprehensive tests for all Livewire components (DeliveryOptionSelectFlux, PatronUDFSelectFlux, PostalCodeSelectFlux).

Component Test Structure

Running Component Tests

All component tests:

Individual component tests:

Test specific component features:

Component Test Coverage

PatronUDFSelectFlux Tests Cover:

• Component instantiation and initialization
• UDF loading based on external label parameter
• Label-specific session management (PatronUDF_{Label})
• Event dispatching (patronUdfUpdated)
• Option filtering and display name customization
• Edge cases (empty values, non-existent labels, whitespace handling)
• Multiple component instances working independently
• View rendering and Flux UI integration

PostalCodeSelectFlux Tests Cover:

• Component instantiation and configuration
• Postal code loading with geographic filtering
• Multiple display formats (full, city_state_zip, city_zip)
• Search and filtering functionality
• Session persistence (PostalCodeID)
• Event dispatching with comprehensive location data
• Database query ordering and optimization
• Edge cases (empty filters, invalid formats)
• Performance considerations for large datasets

Feature Tests Cover:

• Cross-component integration and independence
• Real database interactions with migrations
• Session state persistence across "page loads"
• Component coexistence without interference
• Flux UI template rendering
• Error handling with missing database data

Test Database Setup

Component tests use in-memory SQLite databases with the RefreshDatabase trait:

Testing Component Interactions

Test Event Handling:

Test Session Integration:

Test Component Properties:

Running Tests with Coverage

Component Test Performance

Test execution speed:

• Unit tests: ~50-100ms per test (no database I/O)
• Feature tests: ~200-500ms per test (includes database operations)
• Full component test suite: ~5-10 seconds

Optimizing test performance:

Troubleshooting Tests

Tests not found:

Integration tests skipped: Ensure ENABLE_INTEGRATION_TESTS=true is set

Component tests failing:

Livewire component tests failing:

Coverage requires Xdebug:

Permission errors:

Database-related test failures:

PatronUDFSelectFlux

A dynamic Livewire component that creates select dropdowns from Patron User Defined Fields (UDFs) stored in your database. Perfect for forms that need library-specific custom fields like School, Department, Grade Level, etc.

Features

• Dynamic UDF Loading: Automatically loads options from PatronUdf database records
• External Label Selection: Specify which UDF to use via the patronUdfLabel parameter
• Session Integration: Remembers user's selection with label-specific session keys
• Flux UI Integration: Modern, accessible UI components
• Custom Display Names: Override database values with user-friendly labels
• Event Broadcasting: Notifies parent components of selection changes

Quick Start

To use the PatronUDF component for a "School" selection:

1. In your Livewire component:

2. In your Blade template:

Configuration

1. Database Setup

Ensure your patron_udfs table has records like:

Sample Data:

2. Component Parameters

3. Usage Examples

Basic School Selection:

Department Selection with Custom Placeholder:

Grade Level with Session Integration:

4. Event Handling

The component dispatches patronUdfUpdated events:

5. Session Integration

• Auto-session keys: PatronUDF_{Label} (e.g., PatronUDF_School)
• Persistent selection: User choices persist across browser sessions
• Label-specific: Different UDFs maintain separate session values

6. Customization

Custom Display Names (Advanced): Extend the component to override display names:

7. Troubleshooting

No options appearing:

• Verify PatronUdf record exists with the specified Label
• Check that Display field is true
• Ensure Values field contains comma-separated options
• Confirm database connection is working

Session not persisting:

• Verify Laravel session configuration
• Check session driver settings
• Ensure session middleware is active

Wrong UDF loading:

• Double-check the patronUdfLabel parameter spelling
• Verify Label field in database matches exactly (case-sensitive)
• Check for duplicate Label entries in database

PostalCodeSelectFlux

A comprehensive Livewire component for postal code selection with city, state, and county information. Ideal for address forms, service area selection, and location-based features.

Features

• Rich Location Data: Shows city, state, postal code, and county information
• Multiple Display Formats: Customizable display formats (full, city_state_zip, city_zip, etc.)
• Geographic Filtering: Filter by state, county, or other geographic criteria
• Session Integration: Remembers user's postal code selection
• Flux UI Integration: Modern, accessible select component
• Event Broadcasting: Dispatches detailed postal code information
• Search Functionality: Built-in search and filtering capabilities

Quick Start

To use the postal code component for address selection:

1. In your Livewire component:

2. In your Blade template:

Configuration

1. Database Setup

Ensure your postal_codes table has the structure:

Sample Data:

2. Component Parameters

3. Display Formats

Available formats:

• full: "Denver, CO 80202 (Denver County)"
• city_state_zip: "Denver, CO 80202" (default)
• city_zip: "Denver 80202"
• custom: Use custom formatting method

4. Geographic Filtering

Filter by State:

Filter by Multiple Criteria:

Dynamic Filtering in Parent Component:

5. Usage Examples

Basic Postal Code Selection:

Service Area Selection:

Address Form Integration:

6. Event Handling

The component dispatches comprehensive postalCodeUpdated events:

7. Session Integration

• Session key: PostalCodeID
• Persistent selection: User's postal code choice persists across sessions
• Auto-restoration: Component automatically loads saved selection on mount

8. Advanced Customization

Custom Display Format: Extend the component for custom formatting:

Search Integration:

9. Performance Optimization

Lazy Loading:

Pagination for Large Datasets:

10. Troubleshooting

No postal codes appearing:

• Verify postal_codes table has data
• Check database connection
• Ensure proper column names match model
• Verify filters aren't too restrictive

Performance issues:

• Add database indexes on State, City, PostalCode
• Consider lazy loading for large datasets
• Implement search functionality for better UX

Session not persisting:

• Verify Laravel session configuration
• Check session driver and middleware
• Ensure session storage is writable

Incorrect location data:

• Verify postal code data accuracy in database
• Check PostalCode model fillable fields
• Ensure proper data seeding

Contributing

Please see contributing.md for details and a todolist.

Security

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

Credits

• author name
• All Contributors

License

license. Please see the license file for more information.