{"_id":"558201908625220d00429f24","initVersion":{"_id":"555fbba928249c1900618a85","version":"1.0"},"project":"555fbba928249c1900618a82","user":{"_id":"55648cf93b87582b003ab8b1","username":"","name":"Chris Bunting"},"__v":0,"hidden":false,"createdAt":"2015-06-17T23:24:00.096Z","fullscreen":false,"htmlmode":false,"html":"","body":"The Recurly PHP Client library is an open source library to interact with Recurly's subscription management from your PHP website. The library interacts with Recurly's REST API.\n\nView the [GitHub project site](https://github.com/recurly/recurly-client-php) for a list of requirements and download/install instructions.\n\n* [Configuration](#configuration)\n* [Fetching Linked Resources](#fetching-linked-resources)\n* [Handling Dates](#handling-dates)\n* [Using the API](#using-the-api)\n* [Handling Errors](#handling-errors)\n* [Handle Webhooks](#handle-webhooks)\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Configuration\"\n}\n[/block]\nRequire the `lib/recurly.php` script and setup your [authentication credentials](https://dev.recurly.com/docs/getting-started):\n\n```\nrequire_once('lib/recurly.php');\n\n// Required for the API\nRecurly_Client::$subdomain = 'your-subdomain';\nRecurly_Client::$apiKey = 'abcdef01234567890abcdef01234567890';\n```\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"All the examples will assume that you have properly set up your configuration\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Fetching Linked Resources\"\n}\n[/block]\nWhen fetching objects, some variables will be or embedded objects that can be lazily loaded.  Below is an example for grabbing account details after fetching a subscription.\n\n```\n$subscription = Recurly_Subscription::get('abcdef01234567890abcdef01234567890');\n\n/* fetch the account */\n$account = $subscription->account->get();\nprint $account->account_code;\n```\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Handling Dates\"\n}\n[/block]\nDates from Recurly are converted into [DateTime](http://php.net/manual/en/class.datetime.php) objects, which gives your methods to compare or format dates using that PHP class.\n\n```\n$subscription = Recurly_Subscription::get('abcdef01234567890abcdef01234567890');\nprint $subscription->activated_at->format(DateTime::ISO8601);\n```\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Using the API\"\n}\n[/block]\nEach endpoint is documented with examples [here](https://dev.recurly.com/docs/getting-started).  Feel free to explore them for more information related to specific endpoints.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Handling Errors\"\n}\n[/block]\nWhen using the PHP library, Recurly recommends proper exception handling.  Not handling exceptions properly could result in unexpected results or sudden termination of your code.  Below is a sample example in PHP as how to properly catch exceptions thrown by the Recurly PHP library.\n\n```\ntry {\n  // This will throw a Recurly_NotFoundError exception if the account_code does\n  // not exist:\n  $account = Recurly_Account::get('1');\n\n  $subscription = new Recurly_Subscription();\n  $subscription->account = $account;\n\n  // This will throw a Recurly_ValidationError exception because the\n  // plan_code is missing:\n  $subscription->create();\n}\ncatch (Recurly_NotFoundError $e) {\n  print 'Record could not be found';\n}\ncatch (Recurly_ValidationError $e) {\n  // If there are multiple errors, they are comma delimited:\n  $messages = explode(',', $e->getMessage());\n  print 'Validation problems: ' . implode(\"\\n\", $messages);\n}\ncatch (Recurly_ServerError $e) {\n  print 'Problem communicating with Recurly';\n}\ncatch (Exception $e) {\n  // You could use send these messages to a log for later analysis.\n  print get_class($e) . ': ' . $e->getMessage();\n}\n```\n\nFor a list of possible exception types review: [https://github.com/recurly/recurly-client-php/blob/master/lib/recurly/errors.php](https://github.com/recurly/recurly-client-php/blob/master/lib/recurly/errors.php)\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Handle Webhooks\"\n}\n[/block]\nThere is a built in class to help handle [webhooks](https://docs.recurly.com/push-notifications). For a list of the different webhooks and their format, you can view the [documentation](https://recurly.readme.io/v2.0/page/webhooks)\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"This example is not meant to be put into production but rather to provide you with a starting point for your integration.\"\n}\n[/block]\n```\n// Recurly will POST an XML payload to your URL that you designate\n// in your webhooks configuration\n\n//Get the XML Payload\n$post_xml = file_get_contents (\"php://input\");\n$notification = new Recurly_PushNotification($post_xml);\n//each webhook is defined by a type\nswitch ($notification->type) {\n  case \"successful_payment_notification\":\n    /* process notification here */\n    break;\n  case \"failed_payment_notification\":\n    /* process notification here */\n    break;\n  /* add more notifications to process */\n}\n```\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Support\"\n}\n[/block]\nLooking for help? Please contact <support@recurly.com> or visit [support.recurly.com](https://support.recurly.com/).\n[Stackoverflow](http://stackoverflow.com/questions/tagged/recurly) is also a great place to talk to the community and find answers to common questions.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Announcements\"\n}\n[/block]\nFor the latest API and client library announcements follow Recurly on Twitter and join our Google Group:\n\n- [@recurly](https://twitter.com/recurly)\n- [Recurly Google Group](http://groups.google.com/group/recurly-api)","slug":"php","title":"PHP"}

PHP


The Recurly PHP Client library is an open source library to interact with Recurly's subscription management from your PHP website. The library interacts with Recurly's REST API. View the [GitHub project site](https://github.com/recurly/recurly-client-php) for a list of requirements and download/install instructions. * [Configuration](#configuration) * [Fetching Linked Resources](#fetching-linked-resources) * [Handling Dates](#handling-dates) * [Using the API](#using-the-api) * [Handling Errors](#handling-errors) * [Handle Webhooks](#handle-webhooks) [block:api-header] { "type": "basic", "title": "Configuration" } [/block] Require the `lib/recurly.php` script and setup your [authentication credentials](https://dev.recurly.com/docs/getting-started): ``` require_once('lib/recurly.php'); // Required for the API Recurly_Client::$subdomain = 'your-subdomain'; Recurly_Client::$apiKey = 'abcdef01234567890abcdef01234567890'; ``` [block:callout] { "type": "info", "body": "All the examples will assume that you have properly set up your configuration" } [/block] [block:api-header] { "type": "basic", "title": "Fetching Linked Resources" } [/block] When fetching objects, some variables will be or embedded objects that can be lazily loaded. Below is an example for grabbing account details after fetching a subscription. ``` $subscription = Recurly_Subscription::get('abcdef01234567890abcdef01234567890'); /* fetch the account */ $account = $subscription->account->get(); print $account->account_code; ``` [block:api-header] { "type": "basic", "title": "Handling Dates" } [/block] Dates from Recurly are converted into [DateTime](http://php.net/manual/en/class.datetime.php) objects, which gives your methods to compare or format dates using that PHP class. ``` $subscription = Recurly_Subscription::get('abcdef01234567890abcdef01234567890'); print $subscription->activated_at->format(DateTime::ISO8601); ``` [block:api-header] { "type": "basic", "title": "Using the API" } [/block] Each endpoint is documented with examples [here](https://dev.recurly.com/docs/getting-started). Feel free to explore them for more information related to specific endpoints. [block:api-header] { "type": "basic", "title": "Handling Errors" } [/block] When using the PHP library, Recurly recommends proper exception handling. Not handling exceptions properly could result in unexpected results or sudden termination of your code. Below is a sample example in PHP as how to properly catch exceptions thrown by the Recurly PHP library. ``` try { // This will throw a Recurly_NotFoundError exception if the account_code does // not exist: $account = Recurly_Account::get('1'); $subscription = new Recurly_Subscription(); $subscription->account = $account; // This will throw a Recurly_ValidationError exception because the // plan_code is missing: $subscription->create(); } catch (Recurly_NotFoundError $e) { print 'Record could not be found'; } catch (Recurly_ValidationError $e) { // If there are multiple errors, they are comma delimited: $messages = explode(',', $e->getMessage()); print 'Validation problems: ' . implode("\n", $messages); } catch (Recurly_ServerError $e) { print 'Problem communicating with Recurly'; } catch (Exception $e) { // You could use send these messages to a log for later analysis. print get_class($e) . ': ' . $e->getMessage(); } ``` For a list of possible exception types review: [https://github.com/recurly/recurly-client-php/blob/master/lib/recurly/errors.php](https://github.com/recurly/recurly-client-php/blob/master/lib/recurly/errors.php) [block:api-header] { "type": "basic", "title": "Handle Webhooks" } [/block] There is a built in class to help handle [webhooks](https://docs.recurly.com/push-notifications). For a list of the different webhooks and their format, you can view the [documentation](https://recurly.readme.io/v2.0/page/webhooks) [block:callout] { "type": "warning", "body": "This example is not meant to be put into production but rather to provide you with a starting point for your integration." } [/block] ``` // Recurly will POST an XML payload to your URL that you designate // in your webhooks configuration //Get the XML Payload $post_xml = file_get_contents ("php://input"); $notification = new Recurly_PushNotification($post_xml); //each webhook is defined by a type switch ($notification->type) { case "successful_payment_notification": /* process notification here */ break; case "failed_payment_notification": /* process notification here */ break; /* add more notifications to process */ } ``` [block:api-header] { "type": "basic", "title": "Support" } [/block] Looking for help? Please contact <support@recurly.com> or visit [support.recurly.com](https://support.recurly.com/). [Stackoverflow](http://stackoverflow.com/questions/tagged/recurly) is also a great place to talk to the community and find answers to common questions. [block:api-header] { "type": "basic", "title": "Announcements" } [/block] For the latest API and client library announcements follow Recurly on Twitter and join our Google Group: - [@recurly](https://twitter.com/recurly) - [Recurly Google Group](http://groups.google.com/group/recurly-api)