Download the PHP package wyz/copernica-api without Composer

On this page you can find all versions of the php package wyz/copernica-api. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Informations about the package copernica-api

Copernica REST API PHP tools Build Status

This project contains

Usage

Use the RestClient class and the two other classes mentioned below; act as if CopernicaRestAPI does not exist.

RestClient contains get() / post() / put() and delete() calls (just like the standard CopernicaRestAPI); it also contains two extra calls getEntity() and getEntities() which do some extra checks and are guaranteed to return a valid 'entity' or 'list of entities'. (An 'entity' is something like a profile / subprofile / emailing / database; likely anything that has an ID value.) It is hopefully self-evident which of the three 'get' methods can best be used, based on the API endpoint.

Large sets of entities (larger than the limit which the API allows in one response) need to be fetched in batches. BatchableRestClient is a Client containing some helpful methods: getMoreEntities() and getMoreEntitiesOrdered(). Either of these two methods should be used depending on what data set is being fetched; getMoreEntities() works for all types of entities but has a slightly higher risk of skipping entities in some cases. See the method comments for more detailed info. (Or, for starters, just copy the below example and replace by getMoreEntities() if things don't work.)

The response of some API calls contain lists of other entities inside an entity. This is not very common. (It's likely only the case for 'structure' entities like databases and collections, as opposed to 'user data' entities.) These embedded entities are wrapped inside a similar set of metadata as an API result for a list of entities. While this library does not implement perfect structures to work with embedded entities, it does provide a method to validate and 'unwrap' these metadata so the caller doesn't need to worry about it. An example:

Error handling

If RestClient methods receive an invalid or unrecognized response / fail to get any response from the API, they throw an exception. Callers can influence this behavior and make the class method just return the response instead. Things to know:

Any time you hit an exception that you need to work around (by e.g. fiddling with these constants), but you think actually the class should handle this better: feel free to file a bug report.

Temporary network errors

For some software projects, it is relevant to know which errors can be classified as temporary. (E.g. those that terminate a process on unexpected errors and only want to continue / repeat their actions when specific 'known to be temporary' errors are encountered. Another strategy that could work, but might be dangerous, is to only regard HTTP 400 response codes as permanent, and regard everything else a temporary error - at the risk of a process getting stuck retrying.)

Copernica's service infrastructure is quite stable but hiccups and temporary outages can occur everywhere. This is a semi live document of errors observed:

Temporary:

Not sure:

Some more details

Below text is likely unimportant to most people (who just want to use a REST API client class).

Other contents of this repository

The tests/ directory contains TestApi, a 'test implementation' of the Copernica API, i.e. a class that can be used instead of CopernicaRestAPI and that stores ata internally. Other code in tests/ are PHPUnit tests, and some small test helper classes; a few tests are real unit tests, but most need an API to work against, so they use TestApi.

TestApi should enable writing tests for your own processes which use the REST API. The extra/ directory contains example tests/other code I wrote for my own processes.

Don't use CopernicaRestAPI

It is recommended to not use CopernicaRestAPI directly. I'm using it but keeping it in a separate file, for a combination of overlapping reasons:

The approach does have disadvantages, though:

It's likely that the next step in the evolution of this code will be to bite the bullet and get rid of CopernicaRestAPI / make it only a very thin layer (only to enable emulating API calls by tests). All this is unimportant for 'the 99.99% case' though, which should only use RestClient directly and doesn't need to use the illogical constants. It could take years until the next rewrite, as long as the current code just works for all practical applications we encounter.

Extra branches

* Actually... The first patch doesn't seem to have any additional value anymore. In case you want to know:

Compatibility

The library works with PHP7/8 and probably with PHP5.

While PHP5 is way beyond end-of-life, I'm trying to keep it compatible as long as I don't see a real benefit to using PHP7-only constructs, because I'm still used to it / because who knows what old code companies are still running internally. I won't reject PHP7-only additions though. And test coverage for PHP5 was already dropped because the tests themselves contain PHP7-only constructs, so I won't notice if I accidentally break PHP5 compatibility.

Project name

The package is called "copernica-api" rather than e.g. "copernica-rest-api", to leave open the possibility of adding code to e.g. work with the older SOAP API. (I have some code for processes using SOAP, but more recent work on the v2 REST API indicates this may not be needed anymore - so I haven't polished it up.)

Similar projects

In principle I'm not a fan of creating new projects (like this PHP library) rather than cooperating with existing projects. I have looked around and found several - so at the risk of being pedantic, I feel the need to justify this choice. Maybe this will be a guideline for other people comparing the projects.

If the situation changes and there is value in merging this project into another one, I'm open to it.

Projects found (excluding the ones that just take Copernica's SOAP class and provide a composer.json for it):

Last commit Oct 2018. Uses the Curl code from Copernica's example class with few changes. The class more or less explicitly states that new methods must be created for every single API call - and only three of them are created so far. This cannot be considered "in active development".

Last updated September 2019, and seemingly nearly complete as far as methods go. (Not complete; it's missing EmailingStatistics and EmailingTemplates which I am using.)

This has replaced the original code with Guzzle, which I appreciate. Judging by the code and the README, this has been written by someone who

I can appreciate that last sentiment for 'embedded entities' (like fields inside collections inside the response for a database), which contain layers of metadata that calling code shouldn't need to deal with. However, embedded entities are an outlier, not the norm.

While I am not against using value objects where it has a practical purpose... I tend to favor working with the returned array data if the reasons to do otherwise aren't clear. Wrapping returned data often just obfuscates it. That may be a personal preference.

And I unfortunately cannot derive the practical purpose from the code or the example in the README. The README only documents one example of those embedded entities which IMHO isn't very representative of every day API use.

What I think has much more practical value (generally when dealing with remote APIs) than wrapping array data into separate PHP classes, is doing all necessary checks which code needs to do repeatedly on returned results, so that a caller 1) doesn't need to deal with those; 2) can be absolutely sure that the data returned by a client class is valid. (I favor being really strict and throwing exceptions for any unexpected data, for reason 2.)

So: it would be important to me to integrate the strict checks I have made in the various get() commands, into individual classes in this project. The advantage would likely be that the difference between my various get() calls would disappear, because only one of each maps to each of the API endpoints. However,

For now, I'd rather spend some time writing this README and polishing my existing code to publish it as a separate project, rather than retrofit the checks I need into the copernica-api-php project and add it to / re-test my own live projects after adding EmailingTemplates/EmailingStatistics.

Again, once I see a use for wrapping all data into loads of classes instead of working with simple array data... I'll gladly reconsider adding my code into the copernica-api-php project and retiring this one.

Contributing

If you submit a PR and it's small: tell me explicitly if you don't want me to rebase it / want to keep using your own repository as-is. (If a project is slow moving and the PR changes are not too big, I tend to want to 'merge --rebase' PR's if I can't fast-forward them, to keep the git history uncomplicated for both me and yourself. But that does mean you're forced to change the commit history on your side while you upgrade to my 'merged' upstream version.)

Adding tests to your changes is encouraged, but possibly not required; we'll see about that on a case by case basis. (Unit test coverage isn't complete anyway.)

Authors

Acknowledgments

The result of the partial sponsorship is a component for use in synchronization processes which can update profiles plus attached subprofiles on the basis of imported 'items' - in a trustworthy, efficient and configurable way. If you're in need of such a component, feel free to contact me and state your case for needing it. (It's not yet open sourced as it has cost a lot of paid and unpaid developer hours. The tests and helper code in extra/ give some insight into the robustness of its code.)

License

This library is licensed under the GPL, version 2 or any higher version - except the CopernicaRestAPI class (which is not illegal for me to republish but which is also downloadable from the Copernica website).

(The license may seem slightly odd but is chosen to keep the possibility of distributing the code together with Drupal, which would be a potential issue for the profile import component. If that outlook changes, I might relicense a newer version under either GPLv3 or MIT license.)


All versions of copernica-api with dependencies

PHP Build Version
Package Version
Requires ext-curl Version *
ext-json Version *
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package wyz/copernica-api contains the following files

Loading the files please wait ....