idct/simple-wykop

Wykop.pl API v2 Basic client

dev-master 2020-04-04 06:46 UTC

Requires

• php: ^7.1
• ext-curl: *
• myclabs/php-enum: ^1.7.2

Requires (Dev)

• friendsofphp/php-cs-fixer: ^2.16
• php-coveralls/php-coveralls: ^2.1
• php-mock/php-mock-phpunit: ^2.5
• phpunit/phpunit: ^7.5

MIT

• IDCT Bartosz Pachołek

• php
• web service
• webservice
• wykop
• programista15k

README

Simple PHP client for the Wykop.pl API v2

installation

The best way to install the library in your project is by using Composer:

composer require idct/php-simple-wykop

of course you can still manually include all the required files in your project using using statements yet Composer and autoloading is more than suggested.

TODOs and contribution

The main area which requires a lot of work and contribution is the coverage of dedicated methods. Apart from that any updates on tests (mostly missing) or code-style is always more than welcome! Please create Pull Requests or file Issues with your input.

Usage

First, create an instance:

use IDCT\Wykop\SimpleWykop();
$wykop = new SimpleWykop($appKey, $appSecret);

Where to get $appKey, $appSecret from?

You need to register an API v2 app in the "For programmers" section of Wykop.pl; usually it is here: https://www.wykop.pl/dla-programistow/

If you are creating an application for yourself you can already pass the $connectionKey:

use IDCT\Wykop\SimpleWykop();
$wykop = new SimpleWykop($appKey, $appSecret, $connectionKey);

How to obtain the $connectionKey?

There are two ways to do so:

for applications made for yourself

Simply click the connect button ("Połącz aplikację") on the list of your apps in Wykop's panel: https://www.wykop.pl/dla-programistow/twoje-aplikacje/

for multiple users who authenticate using their browsers

Yet if you want to handle multiple users you need to first make them to connect with your app using Wykop's auth methods:

1. Create an instance of the app and generate the connection url:

$wykop = new SimpleWykop($appKey, $appSecret);
$returnUrl = 'https://mydomain.pl/myscript.php';
$connectUrl = $wykop->getConnectUrl($returnUrl);

$returnUrl should be a script on your server which will handle the response data, which includes user's connection key.

1. Redirect user to the connection url using your own frontend somehow or by calling:

header('Location' . $connectUrl);
exit();

1. In the script which handles your return url parse the response by calling:

$wykopConnect = $wykop->parseWykopConnectData();

By default it expects the returned information to be in connectData GET parameter, but if you handled that somehow differently you can simply pass the base64-encoded array of returned contents as the first argument.

In case of a failure (missing parameters) it will throw an exception.

1. Now set the connectionKey in the instance of your SimpleWykop:

$wykopConnect->setConnectionKey($connectionKey);

And done.

Making requests

It is highly recommended to use dedicated methods, yet if one is not implemented (at most likely it is not) then you can use a generic one:

$response = $this->execute($function, $arguments, $filesInfo, $page);

Arguments:

• $function should be replaced with the name of a method available in Wykop's API. For example "notifications/index".
• $arguments should be an array of parameters required by the function.
• filesData array of files' data posted with the input arguments.
• $page if function can return multiple pages then here you enter page number.

The response - if not a failure - will be an instance of GenericResponse class which holds the whole response as an array accessible using the getData method. If there is a next or previous page then getPaginationNext getPaginationNext will hold values instead of null (urls, ignore the urls when using the library just handle the fact that there is a value).

Dedicated methods

Login

$wykopConnect->login($username);

Will attempt to sign in as the user identified by username (that user must be already linked to your app using the $connectionKey).

On success will return an instance of the Profile entity which holds basic information about the user. loginKey and login attributes of SimpleWykop instance will be also set.

Other option is to sign in manually using:

$wykopConnect->loginManually($username, $loginKey);

Such login attempt will assume that you already know the login key (for example from previous signing in and retrieved it using $wykop->getLoginKey()). Warning: no verification is executed, it assumes that you know what you are doing.

warning: login key is temporary, but you should always try to re-use it as Wykop's API has a very low limit of actions per hour and login attempt is also considered an action.

Dedicated methods will always attempt to re-login in case of a InvalidWykopCredentials exception so be sure to check getLoginKey() in case you store it somewhere after execution of all actions.

Logout

$wykopConnect->logout();

Clears the login and loginKey attributes, but performs no remote actions as simply Wykop's API does not offer such methods.

retrieveNotifications

As the name suggests it retrieves user's notifications, this includes PMs info. Does not include hashtags notifications, for that there is a special method.

It creates an Iterator of class Notifications over GenericResponse which creates new instances of Notification on every iteration therefore be aware of potential memory implications if you iterate the results set over and over.

Sample usage:

$notifications = $wykop->retrieveNotifications();

foreach ($notifications as $notification) {
    var_dump( $notification->getUrl() );
}

Since Notifications extends GenericResponse you can still access raw array of data using getData or informationa about next/prev pages.

retrieveHashtagNotifications

Very similar to the retrieveNotifications method is simply retrieves user's hashtags' notifications.

It creates an Iterator of class Notifications over GenericResponse which creates new instances of Notification on every iteration therefore be aware of potential memory implications if you iterate the results set over and over.

Sample usage:

$notifications = $wykop->retrieveHashtagNotifications();

foreach ($notifications as $notification) {
    var_dump( $notification->getUrl() );
}

Since Notifications extends GenericResponse you can still access raw array of data using getData or informationa about next/prev pages.