Initial commit

.gitignore

@@ -0,0 +1,7 @@
+.phpunit.result.cache
+.idea
+build
+composer.lock
+docs
+vendor
+.php-cs-fixer.cache

CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+All notable changes to `crowdtangle-api` will be documented in this file.
+
+## 1.0.0 - 2022-04-04
+
+- initial release

LICENSE.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) ChrisHardie <[email protected]>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

README.md

@@ -0,0 +1,59 @@
+
+# A minimal PHP implementation of the CrowdTangle API
+
+[![Latest Version on Packagist](https://img.shields.io/packagist/v/chrishardie/crowdtangle-api.svg?style=flat-square)](https://packagist.org/packages/chrishardie/crowdtangle-api)
+[![Total Downloads](https://img.shields.io/packagist/dt/chrishardie/crowdtangle-api.svg?style=flat-square)](https://packagist.org/packages/chrishardie/crowdtangle-api)
+
+This is a minimal PHP implementation of the [CrowdTangle API](https://help.crowdtangle.com/en/articles/1189612-crowdtangle-api). It contains a subset of the methods available. I am open to PRs that add extra methods to the client.
+
+Here are a few examples on how you can use the package:
+
+```php
+$client = new ChrisHardie\CrowdtangleApi\Client($accessToken);
+
+// get lists
+$client->getLists();
+
+// get accounts in a list
+$client->getAccountsForList($listId);
+
+// get posts
+$client->getPosts([
+    'accounts' => '12345678',
+    'startDate' => '2022-03-01',
+]);
+
+// get a single post
+$client->getPost($postId);
+```
+
+View the [full CrowdTangle API Documentation](https://github.com/CrowdTangle/API/wiki) for details on available parameters and syntax.
+
+## Installation
+
+You can install the package via composer:
+
+```bash
+composer require chrishardie/crowdtangle-api
+```
+
+## Testing
+
+```bash
+composer test
+```
+
+## Changelog
+
+Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.
+
+## Credits
+
+- [Chris Hardie](https://github.com/ChrisHardie)
+- [All Contributors](../../contributors)
+
+Inspired and structured after Spatie's [Dropbox API](https://github.com/spatie/dropbox-api).
+
+## License
+
+The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

composer.json

@@ -0,0 +1,43 @@
+{
+    "name": "chrishardie/crowdtangle-api",
+    "description": "A minimal PHP implementation of the CrowdTangle API",
+    "keywords": [
+        "ChrisHardie",
+        "crowdtangle",
+        "api"
+    ],
+    "homepage": "https://github.com/chrishardie/crowdtangle-api",
+    "license": "MIT",
+    "authors": [
+        {
+            "name": "Chris Hardie",
+            "email": "[email protected]",
+            "role": "Developer"
+        }
+    ],
+    "require": {
+        "php": "^8.0",
+        "guzzlehttp/guzzle": "^6.2|^7.0"
+    },
+    "require-dev": {
+        "phpunit/phpunit": "^9.4"
+    },
+    "autoload": {
+        "psr-4": {
+            "ChrisHardie\\CrowdtangleApi\\": "src"
+        }
+    },
+    "autoload-dev": {
+        "psr-4": {
+            "ChrisHardie\\CrowdtangleApi\\Tests\\": "tests"
+        }
+    },
+    "scripts": {
+        "test": "vendor/bin/phpunit"
+    },
+    "config": {
+        "sort-packages": true
+    },
+    "minimum-stability": "dev",
+    "prefer-stable": true
+}

src/Client.php

@@ -0,0 +1,196 @@
+<?php
+
+namespace ChrisHardie\CrowdtangleApi;
+
+use ChrisHardie\CrowdtangleApi\Exceptions\BadRequest;
+use GuzzleHttp\Client as GuzzleClient;
+use GuzzleHttp\ClientInterface;
+use GuzzleHttp\Exception\ClientException;
+use GuzzleHttp\Exception\GuzzleException;
+use JsonException;
+
+class Client
+{
+    /**
+     * @var TokenProvider
+     */
+    private TokenProvider $tokenProvider;
+
+    /**
+     * @var GuzzleClient
+     */
+    protected GuzzleClient $client;
+
+    /**
+     * @param string|null $accessToken
+     * @param GuzzleClient|null $client
+     */
+    public function __construct(string $accessToken = null, ClientInterface $client = null)
+    {
+        if ($accessToken instanceof TokenProvider) {
+            $this->tokenProvider = $accessToken;
+        }
+        if (is_string($accessToken)) {
+            $this->tokenProvider = new InMemoryTokenProvider($accessToken);
+        }
+
+        $this->client = $client ?? new GuzzleClient();
+    }
+
+    /**
+     * Retrieve the lists, saved searches and saved post lists
+     *
+     * @link https://github.com/CrowdTangle/API/wiki/lists
+     *
+     * @return array
+     * @throws BadRequest
+     * @throws GuzzleException
+     * @throws JsonException
+     */
+    public function getLists(): array
+    {
+        $body = $this->endpointRequest('lists');
+        return $body['result']['lists'];
+    }
+
+    /**
+     * Retrieve the accounts for a given list.
+     * Accounts may only be retrieved for lists of type LIST, as saved searches and saved posts
+     * do not have associated accounts.
+     *
+     * @link https://github.com/CrowdTangle/API/wiki/List-Accounts
+     *
+     * @param int $listId
+     * @return array
+     * @throws BadRequest
+     * @throws GuzzleException
+     * @throws JsonException
+     */
+    public function getAccountsForList(int $listId): array
+    {
+        $body = $this->endpointRequest('lists/' . $listId . '/accounts');
+        return $body['result']['accounts'];
+    }
+
+    /**
+     * Retrieve a set of posts for the given parameters.
+     *
+     * @link https://github.com/CrowdTangle/API/wiki/Posts
+     *
+     * @param array|null $parameters
+     * @return array
+     * @throws BadRequest
+     * @throws GuzzleException
+     * @throws JsonException
+     */
+    public function getPosts(?array $parameters = []): array
+    {
+        $body = $this->endpointRequest('posts', $parameters);
+        return $body['result']['posts'];
+    }
+
+    /**
+     * Retrieves a specific post.
+     * The ID format for Facebook and Instagram are different.
+     * For Instagram, it's [post_id]_[page_id]
+     * For Facebook, it's [page_id]_[post_id]
+     *
+     * @link https://github.com/CrowdTangle/API/wiki/Posts#get-postid
+     *
+     * @param string $postId
+     * @return array
+     * @throws BadRequest
+     * @throws GuzzleException
+     * @throws JsonException
+     */
+    public function getPost(string $postId): array
+    {
+        $body = $this->endpointRequest('post/' . $postId);
+        if (! empty($body['result']['posts'][0])) {
+            return $body['result']['posts'][0];
+        }
+        return [];
+    }
+
+    /**
+     * @param string     $endpoint
+     * @param array|null $arguments
+     * @return array
+     *
+     * @throws BadRequest
+     * @throws GuzzleException
+     * @throws JsonException
+     */
+    public function endpointRequest(string $endpoint, ? array $arguments = []): array
+    {
+        try {
+            $response = $this->client->get($this->getEndpointUrl($endpoint), [
+                'headers' => $this->getHeaders(),
+                'query' => $arguments,
+            ]);
+        } catch (ClientException $exception) {
+            $response = $this->endpointRequest($endpoint, $arguments);
+        }
+
+        return json_decode($response->getBody(), true, 512, JSON_THROW_ON_ERROR) ?? [];
+    }
+
+    protected function getEndpointUrl(string $endpoint): string
+    {
+        return "https://api.crowdtangle.com/{$endpoint}";
+    }
+
+    /**
+     * Get the access token.
+     */
+    public function getAccessToken(): string
+    {
+        return $this->tokenProvider->getToken();
+    }
+
+    /**
+     * Set the access token.
+     */
+    public function setAccessToken(string $accessToken): self
+    {
+        $this->tokenProvider = new InMemoryTokenProvider($accessToken);
+
+        return $this;
+    }
+
+    /**
+     * Get the HTTP headers.
+     */
+    protected function getHeaders(array $headers = []): array
+    {
+        $auth = [];
+        if ($this->tokenProvider) {
+            $auth = $this->getHeadersForApiToken($this->tokenProvider->getToken());
+        }
+
+        return array_merge($auth, $headers);
+    }
+
+    /**
+     * @param $token
+     * @return array
+     */
+    protected function getHeadersForApiToken($token): array
+    {
+        return [
+            'x-api-token' => $token,
+        ];
+    }
+
+    /**
+     * @throws JsonException
+     */
+    protected function determineException(ClientException $exception): BadRequest|ClientException
+    {
+        if (in_array($exception->getResponse()->getStatusCode(), [400, 409])) {
+            return new BadRequest($exception->getResponse());
+        }
+
+        return $exception;
+    }
+}

src/Exceptions/BadRequest.php

@@ -0,0 +1,40 @@
+<?php
+
+namespace ChrisHardie\CrowdtangleApi\Exceptions;
+
+use Exception;
+use JsonException;
+use Psr\Http\Message\ResponseInterface;
+
+class BadRequest extends Exception
+{
+    /**
+     * @var ResponseInterface
+     */
+    public ResponseInterface $response;
+
+    /**
+     * The CrowdTangle error code supplied in the response.
+     *
+     * @var int|null
+     */
+    public ?int $crowdtangleCode;
+
+    /**
+     * @throws JsonException
+     */
+    public function __construct(ResponseInterface $response)
+    {
+        $this->response = $response;
+
+        $body = json_decode($response->getBody(), true, 512, JSON_THROW_ON_ERROR);
+
+        if ($body !== null) {
+            if (isset($body['code'])) {
+                $this->crowdtangleCode = $body['code'];
+            }
+
+            parent::__construct($body['message']);
+        }
+    }
+}