zendesk/zendesk_api_client_php

View on GitHub
src/Zendesk/API/Resources/Core/Users.php

Summary

Maintainability
A
0 mins
Test Coverage
<?php

namespace Zendesk\API\Resources\Core;

use Zendesk\API\Exceptions\CustomException;
use Zendesk\API\Exceptions\MissingParametersException;
use Zendesk\API\Exceptions\ResponseException;
use Zendesk\API\Http;
use Zendesk\API\Resources\ResourceAbstract;
use Zendesk\API\Traits\Resource\CreateMany;
use Zendesk\API\Traits\Resource\CreateOrUpdateMany;
use Zendesk\API\Traits\Resource\Defaults;
use Zendesk\API\Traits\Resource\FindMany;
use Zendesk\API\Traits\Resource\MultipartUpload;
use Zendesk\API\Traits\Resource\UpdateMany;
use Zendesk\API\Traits\Utility\InstantiatorTrait;

/**
 * The Users class exposes user management methods
 * Note: you must authenticate as a user!
 *
 * @method Groups groups()
 * @method UserIdentities identities()
 * @method Organizations organizations()
 * @method OrganizationMemberships organizationMemberships()
 * @method OrganizationSubscriptions organizationSubscriptions()
 * @method Requests requests()
 * @method UserTickets tickets()
 */
class Users extends ResourceAbstract
{
    use InstantiatorTrait;

    use Defaults {
        findAll as traitFindAll;
    }
    use MultipartUpload;

    use CreateMany;
    use FindMany {
        findMany as traitFindMany;
    }
    use UpdateMany;
    use CreateOrUpdateMany;

    /**
     * @var UserIdentities
     */
    protected $identities;

    /**
     * {@inheritdoc}
     */
    protected function setUpRoutes()
    {
        parent::setUpRoutes();

        $this->setRoutes([
            'related'                    => 'users/{id}/related.json',
            'merge'                      => 'users/{id}/merge.json',
            'search'                     => 'users/search.json',
            'autocomplete'               => 'users/autocomplete.json',
            'setPassword'                => 'users/{id}/password.json',
            'changePassword'             => 'users/{id}/password.json',
            'updateMany'                 => 'users/update_many.json',
            'createOrUpdate'             => 'users/create_or_update.json',
            'createOrUpdateMany'         => 'users/create_or_update_many.json',
            'createMany'                 => 'users/create_many.json',
            'updateProfileImageFromFile' => 'users/{id}.json',
            'updateProfileImageFromUrl'  => 'users/{id}.json',
        ]);
    }

    /**
     * {@inheritdoc}
     */
    public static function getValidSubResources()
    {
        return [
            'groupMemberships'          => GroupMemberships::class,
            'groups'                    => Groups::class,
            'identities'                => UserIdentities::class,
            'organizations'             => Organizations::class,
            'organizationMemberships'   => OrganizationMemberships::class,
            'organizationSubscriptions' => OrganizationSubscriptions::class,
            'requests'                  => Requests::class,
            'sessions'                  => Sessions::class,
            'tickets'                   => UserTickets::class,
            'tags'                      => Tags::class,
        ];
    }

    /**
     * List all users
     *
     * @param array $params
     *
     * @throws ResponseException
     * @throws \Exception
     * @return \stdClass | null
     */
    public function findAll(array $params = [])
    {
        if (isset($params['organization_id'])) {
            $this->endpoint = "organizations/{$params['organization_id']}/users.json";
        } elseif (isset($params['group_id'])) {
            $this->endpoint = 'groups/' . $params['group_id'] . '/users.json';
        } else {
            $this->endpoint = 'users.json';
        }

        return $this->traitFindAll($params);
    }

    /**
     * Find users by ids or external_ids
     *
     * @param array $params
     *
     * @throws ResponseException
     * @throws \Exception
     * @return \stdClass | null
     */
    public function findMany(array $params = [])
    {
        if (isset($params['ids']) xor isset($params['external_ids'])) {
            if (isset($params['ids'])) {
                $key = 'ids';
                $ids = $params['ids'];
            } elseif (isset($params['external_ids'])) {
                $key = 'external_ids';
                $ids = $params['external_ids'];
            }
        } else {
            throw new \Exception('Missing parameters ids or external_ids');
        }

        return $this->traitFindMany($ids, [], $key);
    }

    /**
     * Get related information about the user
     *
     * @param array $params
     *
     * @throws MissingParametersException
     * @throws ResponseException
     * @throws \Exception
     * @return \stdClass | null
     */
    public function related(array $params = [])
    {
        $params = $this->addChainedParametersToParams($params, ['id' => get_class($this)]);

        if (! $this->hasKeys($params, ['id'])) {
            throw new MissingParametersException(__METHOD__, ['id']);
        }

        $response = Http::send(
            $this->client,
            $this->getRoute(__FUNCTION__, ['id' => $params['id']]),
            ['queryParams' => $params]
        );

        return $response;
    }

    /**
     * Merge user (by default yourself) with the specified user
     *
     * @param array $params
     *
     * @throws MissingParametersException
     * @throws ResponseException
     * @throws \Exception
     * @return \stdClass | null
     */
    public function merge(array $params = [])
    {
        $id = $this->getChainedParameter(get_class($this));
        $mergeMe = ($id === null || $id === 'me');
        $hasKeys = $mergeMe ? ['email', 'password'] : ['id'];

        if (! $this->hasKeys($params, $hasKeys)) {
            throw new MissingParametersException(__METHOD__, $hasKeys);
        }

        $response = Http::send(
            $this->client,
            $this->getRoute(__FUNCTION__, [
                'id' => $mergeMe ? 'me' : $id,
            ]),
            ['postFields' => [$this->objectName => $params], 'method' => 'PUT']
        );

        return $response;
    }

    /**
     * Update multiple users
     *
     * @param array $params
     *
     * @throws MissingParametersException
     * @throws ResponseException
     * @return \stdClass | null
     */
    public function suspend(array $params = [])
    {
        $params = $this->addChainedParametersToParams($params, ['id' => get_class($this)]);
        if (! $this->hasKeys($params, ['id'])) {
            throw new MissingParametersException(__METHOD__, ['id']);
        }
        $params['suspended'] = true;

        return $this->update($params['id'], $params);
    }

    /**
     * Search for users
     *
     * @param array $params Accepts `external_id` & `query`
     *
     * @throws ResponseException
     * @throws \Exception
     * @return \stdClass | null
     */
    public function search(array $params)
    {
        return $this->client->get($this->getRoute(__FUNCTION__), $params);
    }

    /**
     * Requests autocomplete for users
     *
     * @param array $params
     *
     * @throws ResponseException
     * @throws \Exception
     * @return \stdClass | null
     */
    public function autocomplete(array $params)
    {
        $response = Http::send(
            $this->client,
            $this->getRoute(__FUNCTION__),
            ['method' => 'POST', 'queryParams' => $params]
        );

        return $response;
    }

    /**
     * {$@inheritdoc}
     *
     * @return String
     */
    public function getUploadName()
    {
        return 'user[photo][uploaded_data]';
    }

    /**
     * {$@inheritdoc}
     *
     * @return String
     */
    public function getUploadRequestMethod()
    {
        return 'PUT';
    }

    /**
     * Update a user's profile image
     *
     * @param array $params
     *
     * @throws CustomException
     * @throws MissingParametersException
     * @throws ResponseException
     * @throws \Exception
     * @return \stdClass | null
     */
    public function updateProfileImageFromFile(array $params)
    {
        $this->setAdditionalRouteParams(['id' => $this->getChainedParameter(self::class)]);

        return $this->upload($params, __FUNCTION__);
    }

    /**
     * Update a user's profile image
     *
     * @param array $params
     *
     * @throws CustomException
     * @throws MissingParametersException
     * @throws ResponseException
     * @throws \Exception
     * @return \stdClass | null
     */
    public function updateProfileImageFromUrl(array $params)
    {
        if (! isset($params['id']) || empty($params['id'])) {
            $params = $this->addChainedParametersToParams($params, ['id' => self::class]);
        }

        if (! $this->hasKeys($params, ['id', 'url'])) {
            throw new MissingParametersException(__METHOD__, ['id', 'url']);
        }

        $endpoint = $this->getRoute(__FUNCTION__, ['id' => $params['id']]);

        $putData = [
            $this->objectName => [
                'remote_photo_url' => $params['url']
            ]
        ];

        return $this->client->put($endpoint, $putData);
    }

    /**
     * Show the current user
     *
     * @param array $params
     *
     * @throws MissingParametersException
     * @throws ResponseException
     * @return \stdClass | null
     */
    public function me(array $params = [])
    {
        $params['id'] = 'me';

        return $this->find($params['id']);
    }

    /**
     * Sets a user's initial password
     *
     * @param array $params
     *
     * @throws MissingParametersException
     * @throws ResponseException
     * @throws \Exception
     * @return null
     */
    public function setPassword(array $params)
    {
        $params = $this->addChainedParametersToParams($params, ['id' => get_class($this)]);
        if (! $this->hasKeys($params, ['id', 'password'])) {
            throw new MissingParametersException(__METHOD__, ['id', 'password']);
        }
        $id = $params['id'];
        unset($params['id']);

        return $this->client->post($this->getRoute(__FUNCTION__, ['id' => $id]), $params);
    }

    /**
     * Change a user's password
     *
     * @param array $params
     *
     * @throws MissingParametersException
     * @throws ResponseException
     * @throws \Exception
     * @return null
     */
    public function changePassword(array $params)
    {
        $params = $this->addChainedParametersToParams($params, ['id' => get_class($this)]);
        if (! $this->hasKeys($params, ['id', 'previous_password', 'password'])) {
            throw new MissingParametersException(__METHOD__, ['id', 'previous_password', 'password']);
        }
        $id = $params['id'];
        unset($params['id']);

        return $this->client->put($this->getRoute(__FUNCTION__, ['id' => $id]), $params);
    }

    /**
     * Create or updates a user
     *
     * @param array  $params
     *
     * @param string $routeKey
     * @return null|\stdClass
     */
    public function createOrUpdate(array $params, $routeKey = __FUNCTION__)
    {
        $route = $this->getRoute($routeKey, $params);
        return $this->client->post(
            $route,
            [$this->objectName => $params]
        );
    }
}