{"id":34016694,"url":"https://github.com/bmlt-enabled/bmlt-php-query-client","last_synced_at":"2025-12-13T14:04:11.019Z","repository":{"id":314745646,"uuid":"1056607439","full_name":"bmlt-enabled/bmlt-php-query-client","owner":"bmlt-enabled","description":"PHP Client for BMLT Semantic API ","archived":false,"fork":false,"pushed_at":"2025-09-14T13:16:40.000Z","size":230,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-14T15:22:30.229Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://bmlt-enabled.github.io/bmlt-php-query-client/","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bmlt-enabled.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-14T12:57:13.000Z","updated_at":"2025-09-14T13:16:38.000Z","dependencies_parsed_at":"2025-09-14T15:22:50.749Z","dependency_job_id":null,"html_url":"https://github.com/bmlt-enabled/bmlt-php-query-client","commit_stats":null,"previous_names":["bmlt-enabled/bmlt-php-query-client"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/bmlt-enabled/bmlt-php-query-client","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bmlt-enabled%2Fbmlt-php-query-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bmlt-enabled%2Fbmlt-php-query-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bmlt-enabled%2Fbmlt-php-query-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bmlt-enabled%2Fbmlt-php-query-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bmlt-enabled","download_url":"https://codeload.github.com/bmlt-enabled/bmlt-php-query-client/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bmlt-enabled%2Fbmlt-php-query-client/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":27706768,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-12-13T02:00:09.769Z","response_time":147,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-12-13T14:04:10.432Z","updated_at":"2025-12-13T14:04:11.008Z","avatar_url":"https://github.com/bmlt-enabled.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# BMLT PHP Query Client\n\n[![PHP Version](https://img.shields.io/badge/PHP-8.1%2B-blue.svg)](https://php.net/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Composer](https://img.shields.io/badge/composer-ready-green.svg)](https://packagist.org/)\n\nA modern PHP client for querying BMLT (Basic Meeting List Tool) servers with built-in geocoding support using Guzzle HTTP client.\n\n## Features\n\n- 🚀 **Modern PHP 8.1+** - Uses enums, readonly classes, and named parameters\n- 🏛️ **Complete BMLT API coverage** - All semantic endpoints supported\n- 🌍 **Built-in geocoding** - Uses OpenStreetMap Nominatim for address-to-coordinates conversion\n- 🔍 **Type-safe API** - Full type definitions with readonly data objects\n- ⚡ **HTTP client** - Built on Guzzle HTTP with proper error handling\n- 📦 **Composer ready** - Easy installation via Composer\n- 🎯 **Well tested** - Comprehensive unit and integration tests\n- 🛠️ **Developer friendly** - Clear exceptions and validation\n\n## Requirements\n\n- PHP 8.1 or higher\n- ext-curl\n- ext-json\n\n## Installation\n\n```bash\ncomposer require bmlt-enabled/bmlt-php-query-client\n```\n\n## Quick Start\n\n### Basic Usage\n\n```php\n\u003c?php\n\nuse BmltEnabled\\BmltQueryClient\\Client\\BmltClient;\nuse BmltEnabled\\BmltQueryClient\\Types\\VenueType;\nuse BmltEnabled\\BmltQueryClient\\Types\\Weekday;\n\n// Initialize the client\n$client = new BmltClient(\n    rootServerUrl: 'https://latest.aws.bmlt.app/main_server' // NYC demo server\n);\n\n// Search for meetings\n$meetings = $client-\u003esearchMeetings([\n    'venue_types' =\u003e VenueType::VIRTUAL-\u003evalue,\n    'page_size' =\u003e 10,\n]);\n\nforeach ($meetings as $meeting) {\n    echo \"Meeting: {$meeting-\u003emeeting_name}\\n\";\n    echo \"Time: {$meeting-\u003estart_time}\\n\";\n    if ($meeting-\u003evirtual_meeting_link) {\n        echo \"Link: {$meeting-\u003evirtual_meeting_link}\\n\";\n    }\n    echo \"---\\n\";\n}\n```\n\n### Using the Factory\n\n```php\n\u003c?php\n\nuse BmltEnabled\\BmltQueryClient\\BmltQueryClient;\n\n// Create client using factory method\n$client = BmltQueryClient::create(\n    rootServerUrl: 'https://your-bmlt-server.org/main_server'\n);\n\n$serverInfo = $client-\u003egetServerInfo();\necho \"Server version: {$serverInfo-\u003eversion}\\n\";\n```\n\n## API Reference\n\n### Client Configuration\n\n```php\n$client = new BmltClient(\n    rootServerUrl: 'https://your-server.org/main_server', // Required\n    defaultFormat: BmltDataFormat::JSON, // Optional\n    timeout: 30, // Request timeout in seconds\n    userAgent: 'my-app/1.0.0', // Custom user agent\n    enableGeocoding: true, // Enable geocoding features\n);\n```\n\n### Search Methods\n\n#### Search Meetings\n\n```php\n// Basic search\n$meetings = $client-\u003esearchMeetings([\n    'weekdays' =\u003e [Weekday::SUNDAY-\u003evalue, Weekday::MONDAY-\u003evalue],\n    'venue_types' =\u003e VenueType::IN_PERSON-\u003evalue,\n    'page_size' =\u003e 20,\n]);\n\n// Search by coordinates\nuse BmltEnabled\\BmltQueryClient\\Types\\Coordinates;\n\n$coordinates = new Coordinates(40.7580, -73.9855); // Times Square\n$nearbyMeetings = $client-\u003esearchMeetingsByCoordinates(\n    $coordinates,\n    radiusMiles: 5.0,\n    searchParams: ['page_size' =\u003e 10]\n);\n\n// Search by address (uses geocoding)\n$addressMeetings = $client-\u003esearchMeetingsByAddress(\n    address: 'Times Square, New York, NY',\n    radiusMiles: 2.0,\n    sortByDistance: true,\n    searchParams: ['venue_types' =\u003e VenueType::VIRTUAL-\u003evalue]\n);\n```\n\n#### Server Information\n\n```php\n// Get server info\n$serverInfo = $client-\u003egetServerInfo();\necho \"Version: {$serverInfo-\u003eversion}\\n\";\necho \"Languages: \" . implode(', ', $serverInfo-\u003elangs ?? []) . \"\\n\";\n\n// Get meeting formats\n$formats = $client-\u003egetFormats();\nforeach ($formats as $format) {\n    echo \"{$format-\u003ekey_string}: {$format-\u003ename_string}\\n\";\n}\n\n// Get service bodies\n$serviceBodies = $client-\u003egetServiceBodies();\nforeach ($serviceBodies as $serviceBody) {\n    echo \"{$serviceBody-\u003ename} ({$serviceBody-\u003etype})\\n\";\n}\n```\n\n#### Geocoding\n\n```php\n// Geocode an address\n$result = $client-\u003egeocodeAddress('Central Park, New York, NY');\necho \"Coordinates: {$result-\u003ecoordinates-\u003elatitude}, {$result-\u003ecoordinates-\u003elongitude}\\n\";\necho \"Address: {$result-\u003edisplay_name}\\n\";\n\n// Reverse geocode coordinates\n$coordinates = new Coordinates(40.7614, -73.9776);\n$address = $client-\u003ereverseGeocode($coordinates);\necho \"Address: {$address-\u003edisplay_name}\\n\";\n```\n\n### Fluent Query Builder\n\n```php\nuse BmltEnabled\\BmltQueryClient\\Client\\{MeetingQueryBuilder, QuickSearch};\n\n// Complex fluent query\n$eveningVirtual = (new MeetingQueryBuilder($client))\n    -\u003evirtualOnly()\n    -\u003estartingAfter(17, 0)  // After 5 PM\n    -\u003eendingBefore(21, 0)   // Before 9 PM\n    -\u003eonWeekdays(Weekday::MONDAY, Weekday::FRIDAY)\n    -\u003epaginate(10)\n    -\u003eexecute();\n\n// Quick search patterns\n$quickSearch = new QuickSearch($client);\n\n$todaysMeetings = $quickSearch-\u003etoday()-\u003eexecute();\n$tonightVirtual = $quickSearch-\u003etonight()-\u003evirtualOnly()-\u003eexecute();\n$weekendInPerson = $quickSearch-\u003eweekend()-\u003einPersonOnly()-\u003eexecute();\n\n// Geographic search with fluent interface\n$nearbyMeetings = (new MeetingQueryBuilder($client))\n    -\u003einPersonOnly()\n    -\u003emorning()\n    -\u003eexecuteNearAddress('Times Square, NY', 2.0);\n```\n\n### Data Types\n\nThe library provides strongly-typed data objects:\n\n#### Meeting Object\n\n```php\n// Meeting properties\n$meeting-\u003eid_bigint;           // Meeting ID\n$meeting-\u003emeeting_name;        // Meeting name\n$meeting-\u003eweekday_tinyint;     // Day of week (1=Sunday)\n$meeting-\u003estart_time;          // Start time (HH:MM)\n$meeting-\u003evenue_type;          // 1=In-person, 2=Virtual, 3=Hybrid\n$meeting-\u003evirtual_meeting_link; // Virtual meeting URL\n$meeting-\u003elatitude;            // Latitude\n$meeting-\u003elongitude;           // Longitude\n$meeting-\u003edistance_in_miles;   // Distance (when searching by location)\n// ... and many more\n```\n\n#### Enums\n\n```php\nuse BmltEnabled\\BmltQueryClient\\Types\\{Weekday, VenueType, Language, BmltDataFormat};\n\n// Weekday enum (BMLT uses 1-7, Sunday=1)\nWeekday::SUNDAY;    // 1\nWeekday::MONDAY;    // 2\n// ... etc\n\n// Venue types\nVenueType::IN_PERSON; // 1\nVenueType::VIRTUAL;   // 2\nVenueType::HYBRID;    // 3\n\n// Supported languages\nLanguage::ENGLISH;    // 'en'\nLanguage::SPANISH;    // 'es'\n// ... etc\n\n// Data formats\nBmltDataFormat::JSON; // 'json'\nBmltDataFormat::CSV;  // 'csv'\n// ... etc\n```\n\n## Error Handling\n\nThe library provides comprehensive error handling with specific exception types:\n\n```php\nuse BmltEnabled\\BmltQueryClient\\Exceptions\\BmltQueryException;\n\ntry {\n    $meetings = $client-\u003esearchMeetings(['invalid' =\u003e 'parameter']);\n} catch (BmltQueryException $e) {\n    echo \"Error type: {$e-\u003egetType()}\\n\";\n    echo \"User message: {$e-\u003egetUserMessage()}\\n\";\n    \n    if ($e-\u003eisRetryable()) {\n        echo \"This error can be retried\\n\";\n    }\n    \n    if ($e-\u003eisType(BmltQueryException::TYPE_GEOCODING_ERROR)) {\n        echo \"Geocoding failed\\n\";\n    }\n}\n```\n\n### Exception Types\n\n- `TYPE_NETWORK_ERROR` - Network connectivity issues (retryable)\n- `TYPE_TIMEOUT_ERROR` - Request timeout (retryable)\n- `TYPE_VALIDATION_ERROR` - Invalid parameters (not retryable)\n- `TYPE_GEOCODING_ERROR` - Geocoding service error (retryable)\n- `TYPE_RESPONSE_ERROR` - Invalid server response (retryable for 5xx)\n- `TYPE_RATE_LIMIT_ERROR` - Too many requests (retryable)\n\n## Configuration\n\n### Runtime Configuration\n\nYou can update client settings after initialization:\n\n```php\n// Update user agent\n$client-\u003esetUserAgent('my-updated-app/2.0.0');\necho $client-\u003egetUserAgent(); // 'my-updated-app/2.0.0'\n\n// Update timeout\n$client-\u003esetTimeout(60); // 60 seconds\necho $client-\u003egetTimeout(); // 60\n\n// Update root server URL\n$client-\u003esetRootServerUrl('https://new-server.org/main_server');\necho $client-\u003egetRootServerUrl();\n\n// Update default format\n$client-\u003esetDefaultFormat(BmltDataFormat::JSONP);\necho $client-\u003egetDefaultFormat()-\u003evalue; // 'jsonp'\n```\n\n### Geocoding Options\n\n```php\nuse BmltEnabled\\BmltQueryClient\\Services\\GeocodingService;\n\n// Create custom geocoding service\n$geocodingService = new GeocodingService(\n    timeout: 10,\n    retryCount: 3,\n    userAgent: 'my-app/1.0.0',\n    countryCode: 'us', // Bias results to US\n    viewbox: [-74.2, 40.4, -73.7, 40.9], // NYC bounding box [w,s,e,n]\n    bounded: true, // Restrict to viewbox\n);\n\n$client = new BmltClient(\n    rootServerUrl: 'https://your-server.org/main_server',\n    geocodingService: $geocodingService\n);\n```\n\n## Testing\n\nThe library includes comprehensive tests:\n\n```bash\n# Run unit tests\n./vendor/bin/phpunit --testsuite=\"Unit Tests\"\n\n# Run integration tests (requires internet connection)\n./vendor/bin/phpunit --testsuite=\"Integration Tests\"\n\n# Run all tests\n./vendor/bin/phpunit\n\n# Run with coverage (requires xdebug)\n./vendor/bin/phpunit --coverage-html coverage\n```\n\n## API Documentation\n\nThe library includes comprehensive PHPDoc annotations. You can generate HTML API documentation using:\n\n```bash\n# Generate API documentation\ncomposer docs\n\n# View documentation\nopen docs/api/index.html\n```\n\nThe generated documentation includes:\n- Complete API reference for all classes, methods, and properties\n- Usage examples and code samples\n- Type information and parameter descriptions\n- Exception documentation\n- Inheritance diagrams\n\n## Development\n\n```bash\n# Install dependencies\ncomposer install\n\n# Run tests\ncomposer test\n\n# Static analysis\ncomposer analyse\n\n# Code style check\ncomposer cs-check\n\n# Fix code style\ncomposer cs-fix\n\n# Generate documentation\ncomposer docs\n```\n\n## Examples\n\nSee the `examples/` directory for complete working examples:\n\n- [basic-usage.php](examples/basic-usage.php) - Basic API usage examples\n- [geocoding.php](examples/geocoding.php) - Geocoding examples\n- [error-handling.php](examples/error-handling.php) - Error handling examples\n\n## License\n\nMIT License. See [LICENSE](LICENSE) file for details.\n\n## Contributing\n\nContributions are welcome! Please read the contributing guidelines and submit pull requests.\n\n## Support\n\n- [Issues](https://github.com/bmlt-enabled/bmlt-php-query-client/issues)\n- [BMLT Documentation](https://bmlt.app/documentation/)\n\n## Related Projects\n\n- [bmlt-query-client](https://github.com/bmlt-enabled/bmlt-query-client) - TypeScript/JavaScript version\n- [BMLT Root Server](https://github.com/bmlt-enabled/bmlt-root-server) - The BMLT server software","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbmlt-enabled%2Fbmlt-php-query-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbmlt-enabled%2Fbmlt-php-query-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbmlt-enabled%2Fbmlt-php-query-client/lists"}