<!--
source: https://draugiem.eu/applications/dev/docs/php/
format: markdown (generated for LLM / machine consumption)
language: lv
index: https://draugiem.eu/applications/dev/docs/llms.txt
-->

# Draugiem.lv API PHP bibliotēka

## 1. Ievads

Lai aplikāciju izstrādi padarītu ātrāku un vienkāršāku, esam izveidojuši PHP bibliotēku, kas veic API izsaukumus un automātiski pārveido pieprasītos datus uz PHP datu struktūrām. PHP bibliotēka var tikt izmantota gan portālā integrētajām aplikācijām, gan draugiem.lv Pases aplikācijām.

Bibliotēka darbojas PHP5 vidē un tiek izmantots PHP sesiju mehānisms, lai uzglabātu lietotāja datus sesijā. Lai darbotos API izsaukumi, PHP konfigurācijā jābūt atļautai iespējai atvērt tīmekļa adreses, izmantojot `file_get_contents` funkciju (jābūt ieslēgtam `allow_url_fopen` konfigurācijas uzstādījumam).

[Draugiem.lv API PHP bibliotēka un tās izmantošanas paraugi](https://github.com/Draugiem/draugiem-php-sdk)

Lai varētu savā aplikācijā izmantot API bibliotēku, tajā ir jāiekļauj fails `DraugiemApi.php`.

## 2. Lietotāju dati PHP bibliotēkā

API bibliotēkas funkcijas, kas atgriež lietotāju datus, tos atgriež kā PHP masīvu, kura struktūra ir šāda:

```
array (
        'uid' => 491171,        //Draugiem.lv lietotāja ID
        'name' => 'Jānis',      //Vārds
        'surname' => 'Bērziņš', //Uzvārds
        'age' => 26,    //Vecums (vai false, ja vecums slēpts)
        'adult' => true,//true, ja lietotājs sasniedzis 18 g.vecumu(arī ja vecums slēpts)
        //lietotāja profila attēla URL vai false, ja tas nav pievienots
        'img' => 'https://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg',
        'sex' => 'M',   //dzimums - M-vīrietis, F-sieviete
)
```

Ja funkcija atgriež informāciju par vairākiem lietotājiem (piemēram, draugu sarakstu), tad atgrieztie dati ir masīvs no vairākiem lietotāju datu masīviem, kurā katra elementa atslēga ir lietotāja ID. Ja pieprasīti tikai viena lietotāja profila dati, tiek atgriezts tikai atbilstošā lietotāja datu masīvs.

## 3. Sesijas izveidošana un uzturēšana

API bibliotēka izmanto PHP sesiju mehānismu, lai sesijas ietvaros uzglabātu informāciju par aktīvo draugiem.lv lietotāju. Lai sāktu izmantot draugiem.lv API bibliotēku, jāizveido `DraugiemApi` objekts, konstruktoram padodot aplikācijas ID un API atslēgu. Pēc tam jāizsauc metode `getSession`, kas caur draugiem.lv API veic lietotāja autentifikāciju un iegūst lietotāja datus.

Aplikācijām, kas integrētas draugiem.lv, šī funkcija arī pārbauda, vai lietotāja draugiem.lv sesija joprojām ir aktīva (tāpēc aplikācijas pašai nav nepieciešams veikt `session_check` pieprasījumus).

Draugiem.lv Pases aplikācijām metode tikai veic autentifikāciju un datu iegūšanu, bet lietotāja sesija netiek sasaistīta ar draugiem.lv sesiju.

Ja metode atgriež `true`, tad sesijas izveidošana ir bijusi veiksmīga un lietotājs ir ienācis aplikācijā.:

```php
<?php

include 'DraugiemApi.php';//API bibliotēka

$app_key = 'd6949661ccde33a65d98653043bc3119';//API atslēga
$app_id = 999;//Aplikācijas ID

//Izveido API objektu
$draugiem = new DraugiemApi($app_id, $app_key);

//Sāk sesiju (ja netiek sākta šeit, tad tā tiek automātiski
//izveidota getSession izsaukuma laikā).
session_start();

if($draugiem->getSession()){

        //Autorizācija sekmīga
        //Lietotāja dati ir pieejami pārējām API funkcijām

        $user = $draugiem->getUserData();//Lietotāja profila datu iegūšana

        //Izdrukājam sveicienu lietotājam
        if($user['img']){
                echo '<img src="'.$user['img'].'" alt="" /><br />';
        }
        echo 'Sveiki, '.$user['name'].' '.$user['surname'].'!<br />';

        $uid = $draugiem->getUserId(); //Iegūst draugiem.lv lietotāja ID

        $count = $draugiem->getFriendCount();//Iegūst lietotāja draugu skaitu šajā aplikācijā

        echo 'Šo aplikāciju lieto vēl '.$count.' tavi draugi.';

} else {
        echo 'Authorization failed';
        //Sesijas izveidošana neveiksmīga.
        //Lietotājs vai nu izgājis no draugiem.lv vai
        //nav izdevies aplikācijas autorizācijas pieprasījums.

        //Draugiem.lv Pases aplikācijai šādā situācijā būtu jāattēlo
        //saite uz pieteikšanās logu.
}
```

## 4. Piekļuve lietotāju datiem ārpus sesijas

Ja nepieciešams izsaukt API funkcijas, kādam lietotājam, kas nav aktīvais sesijas lietotājs (piemēram, lai ievietotu paziņojumu lietotāja profila jaunumos, kamēr viņš nelieto aplikāciju), jāizveido jauns `DraugiemApi` objekts, konstruktoram padodot trešo parametru - lietotāja API atslēgu. Šim objektam iespējams izsaukt tās pašas metodes ko objektam, kas pieder aktīvajam sesijas lietotājam.:

```php
$draugiem2 = new DraugiemApi($app_id, $app_key, $user_key);
$draugiem2 -> addNotification('Tev ir jauna vēstule');
```

Lietotāja API atslēgu iespējams iegūt ar metodi `getUserKey` pēc tam, kad viņš ir veiksmīgi autentificēts aplikācijā ar `getSession` metodi. Lai varētu atslēgu izmantot, kamēr lietotājs neizmanto aplikāciju, aplikācijai tā ir jāuzglabā pie sevis.

Lietotāja API atslēga nemainās, kamēr lietotājs neizdzēš aplikāciju no profila vai arī nenomaina savu draugiem.lv lietotāja paroli. Lai nodrošinātu, ka aplikācijai vienmēr pieejama pareizā atslēga, vēlams pēc sesijas izveidošanas pārliecināties, ka atslēga nav mainījusies, un vajadzības gadījumā saglabāt jauno atslēgu.

## 5. API klases metožu apraksts

### 5.1. addActivity($text, $prefix, $link)

Pievieno ierakstu lietotāja profila aktivitātēs formā `{$prefix} <a href="{$link}">{text}</a>`. Pie ieraksta redzama aplikācijas uzstādījumos norādītā ikona. Lai šī metode darbotos, aplikācijai jābūt atļautai aktivitāšu pievienošanai. Katram lietotājam aplikācija var izveidot ne vairāk kā vienu aktivitāti diennaktī.

- **`$text`**: Aktivitātes klikšķināmās saites teksts (maksimālais garums 100 simboli)
- **`$prefix`**: Teksts, kas redzams pirms klikšķināmās saites (neobligāts, maksimālais garums 50 simboli)
- **`$link`**: Adrese, uz ko ved klikšķināmā saite (neobligāts, maksimālais garums 100 simboli, nenorādot saiti, aktivitāte vedīs uz aplikācijas sākumlapu). Integrētajām aplikācijām saitē jānorāda adrese, kas tiks attēlota iframe logā, nevis aplikācijas adrese portālā.
- **Atgriežamā vērtība**: `true`, ja aktivitāti izdevies pievienot, `false`, ja nav izdevies.

### 5.2. addNotification($text, $prefix, $link, $creator)

Pievieno paziņojumu lietotāja profila jaunumos formā `{$prefix} <a href="{$link}">{text}</a>`. Pie ieraksta redzama aplikācijas uzstādījumos norādītā ikona. Lai šī metode darbotos, aplikācijai jābūt atļautai profila jaunumu pievienošanai. Katram lietotājam aplikācija var izveidot ne vairāk kā četrus profila jaunumus diennaktī, ne ātrāk kā stundu pēc iepriekšējā pievienotā profila jaunuma.

- **`$text`**: Paziņojuma klikšķināmās saites teksts (maksimālais garums 100 simboli)
- **`$prefix`**: Teksts, kas redzams pirms klikšķināmās saites (neobligāts, maksimālais garums 50 simboli)
- **`$link`**: Adrese, uz ko ved klikšķināmā saite (neobligāts, maksimālais garums 100 simboli, nenorādot saiti, tā vedīs uz aplikācijas sākumlapu). Integrētajām aplikācijām saitē jānorāda adrese, kas tiks attēlota iframe logā, nevis aplikācijas adrese portālā.
- **`$creator`**: Draugiem.lv lietotāja ID, kas tiks attēlots kā paziņojuma autors (neobligāts; ID īpašniekam jābūt reģistrētam aplikācijas lietotājam; nenorādot ID, kā paziņojuma autors tiks attēlots aplikācijas nosaukums)
- **Atgriežamā vērtība**: `true`, ja paziņojumu izdevies pievienot, `false`, ja nav izdevies.

### 5.3. apiCall($action, $args, $method = 'GET')

Izsauc draugiem.lv API pieprasījumu un atgriež atbildi kā PHP datu struktūru. Pārsvarā šo metodi izmanto citas draugiem.lv PHP bibliotēkas metodes, tāpēc tiešā veidā to vajadzīgs izsaukt tikai tad, ja jāizsauc kāds API pieprasījums, kam PHP bibliotēkā nav paredzēta atsevišķa metode. Noklusētā REQUEST metode ir 'GET', bet vajadzības gadījumā iespējams padot arī 'POST'.

- **`$action`**: Veicamā API pieprasījuma nosaukums (API pieprasījuma *action* parametra vērtība)
- **`$args`**: Asociatīvais masīvs ar pieprasījumam padodamajiem parametriem un tiem atbilstošajām vērtībām (masīvā nav jāiekļauj *action*, *app* un *apikey* parametri, kas pieliekas automātiski)
- **`$method`**: Veicamā API pieprasījuma tips. Pēc noklusējuma tas ir 'GET', bet to var nomainīt uz 'POST'.
- **Atgriežamā vērtība**: Metode atgriež PHP masīvu ar API pieprasījuma atbildes datiem vai `false`, ja pieprasījums nav izdevies, vai atgriezta API kļūda.

### 5.4. checkFriendship($uid, $uid2)

Pārbauda, vai divi aplikācijas lietotāji savā starpā ir draugi.

- **`$uid`**: Pirmā lietotāja ID
- **`$uid2`**: Otrā lietotāja ID (neobligāts, nenorādot šo parametru, tiks pārbaudīta `$uid` un aktīvā aplikācijas lietotāja draudzība)
- **Atgriežamā vērtība**: `true`, ja lietotāji savā starpā ir draugi, `false`, ja pieprasījums nav izdevies, lietotāji nav draugi vai kāds no viņiem nav aplikācijas lietotājs.

### 5.5. cookieFix()

Mēģina apiet sīkdatņu (*cookies*) izveidošanas ierobežojumus *Internet Explorer* un *Safari* pārlūkprogrammās. Šī metode jāizsauc pašā koda sākumā, pirms `getSession()`. Metode automātiski nosaka lietotāja pārlūkprogrammas versiju, tāpēc var tikt izsaukta nepārbaudot, kādu pārlūku lietotājs izmanto.

Metode neko neatgriež un nesaņem nekādus papildu parametrus. Tā jālieto tikai portālā integrētajām aplikācijām, kas izmanto *iframe*.

### 5.6. getAppUsers ($page, $limit, $return_ids)

Atgriež lappusi ar aplikācijas lietotājiem (saraksta sākumā būs tie, kas pēdējie pievienojušies aplikācijai). Iespējams atgriezt vai nu sarakstu ar lietotāju ID vai arī pilnus lietotāju profila datus.

- **`$page`**: Atgriežamās lietotāju lappuses numurs, kas jāatgriež (numerācija sākas ar 1)
- **`$limit`**: Vajadzīgais lietotāju skaits vienā lapā (maksimālā atļautā vērtība 200)
- **`$return_ids`**: `true`, ja vajadzīgs atgriezt tikai lietotāju ID vai `false` (noklusētā vērtība), ja vajadzīgi pilni lietotāju dati.
- **Atgriežamā vērtība**: Masīvs ar lietotāju ID vai profila datiem vai `false`, ja pieprasījums nav izdevies.

### 5.7. getFriendCount()

Iegūst lietotāja draugu skaitu starp aplikācijas lietotājiem. Atgriež draugu skaitu vai `false`, ja pieprasījums nav izdevies.

### 5.8. getInviteInfo()

Iegūst informāciju par uzaicinājumu, ko lietotājs apstiprinājis, kad sācis lietot aplikāciju. Darbojas tikai jauna lietotāja pirmās sesijas laikā. Metode jāizsauc pēc `getSession` izsaukuma.

Ja informācija par uzaicinājumu ir atrasta, metode atgriež datus ar šādu struktūru:

```
array(
        'inviter' => 123, //Lietotāja ID, kas sūtījis uzaicinājumu
        'extra' => '' //Papildu dati, kas ļauj identificēt uzaicinājumu, ja aplikācijas izstrādātājs tādus pievienojis.
)
```

Ja informācija nav atrasta, metode atgriež `false`

### 5.9. getJavascript($resize_container, $callback_html)

Atgriež HTML kodu, kas jāizvada lapā, lai tajā būtu pieejamas draugiem.lv Javascript API funkcijas. Šī iespēja attiecas tikai uz portālā integrētajām aplikācijām. Metode jāizsauc pēc `getSession` izsaukšanas un atgrieztais kods jāizvada starp lapas `<head>` tagiem.

- **`$resize_container`**: Lapas HTML elementa ID, pēc kura izmēriem jāveic automātiska draugiem.lv iframe loga vertikālā izmēra maiņa. Nenorādot šo parametru, automātiska izmēra maiņa netiks veikta.
- **`$callback_html`**: [callback.html](https://draugiem.eu/applications/external/callback.html) faila adrese uz aplikācijas servera, norādot pilnu domēnu. Šis parametrs ir neobligāts, bet, nenorādot to, aplikācija nevarēs saņemt atbildes vērtības no izsauktajām Javascript API funkcijām.
- **Atgriežamā vērtība**: HTML kods, kas jāizvada aplikācijas lapā.

### 5.10. getLoginButton($redirect_url, $popup)

Atgriež HTML kodu, kas ļauj izvadīt lapā draugiem.lv pases pieteikšanās pogu. Metode attiecas tikai uz draugiem.lv pases aplikācijām.

- **`$redirect_url`**: Adrese, uz kuru jāpārsūta lietotājs pēc pieteikšanās ar draugiem.lv pasi
- **`$popup`**: Vai draugiem.lv pases pietiekšanās logu jāatver jaunā izlecošajā logā. (`true` - jā, `false` - nē)
- **Atgriežamā vērtība**: HTML kods, kas jāizvada lapā vietā, kur nepieciešama pieteikšanās poga.

### 5.11. getLoginUrl($redirect_url)

Atgriež WWW adresi draugiem.lv pases pieteikšanās logam ar norādīto atpakaļpārsūtīšanas adresi.

- **`$redirect_url`**: Adrese, uz kuru jāpārsūta lietotājs pēc pieteikšanās ar draugiem.lv pasi
- **Atgriežamā vērtība**: Draugiem.lv pases pieteikšanās loga adrese.

### 5.12. getSession()

Veic draugiem.lv lietotāja autentifikāciju un iegūst pamatinformāciju par lietotāju. **Vienmēr jāizsauc pirms pārējām klases metodēm**, izņemot gadījumus, kad bibliotēka tiek izmantota, norādot lietotāja API atslēgu konstruktorā. Darbībai tiek izmantots PHP iebūvētais sesiju mehānisms. Integrētajām aplikācijām šī metode arī periodiski veic sesijas pārbaudi ar `session_check` pieprasījumu.

- **Atgriežamā vērtība**: `true`, ja autentifikācija veiksmīga un iegūti derīgi lietotāja dati, `false`, ja autentifikācija nav veiksmīga vai lietotāja sesija beigusies.

### 5.13. getSessionDomain()

Atgriež draugiem.lv domēna adresi, no kura lietotājs ienācis aplikācijā. Metode attiecas tikai uz integrētajām aplikācijām. Aplikācijai var būt vajadzīgs zināt domēnu, piemēram, lai korekti attēlotu saites uz lietotāja profiliem. Tipiskā gadījumā domēna vērtība būs `www.draugiem.lv`, taču iespējamas arī citas vērtība, piemēram, ja lietotājs lieto draugiem.lv citā valodā.

### 5.14. getUserCount()

Iegūst aplikācijas reģistrēto lietotāju skaitu. Atgriež lietotāju skaitu vai `false`, ja pieprasījums nav izdevies.

### 5.15. getUserData($ids)

Atgriež pieprasīto lietotāju profila informāciju.

- **`$ids`**: Norāda, kuru lietotāju datus atgriezt. Ja norādīts masīvs ar lietotāju ID (maksimāli 100 vērtības), tiek atgriezts masīvs ar norādīto lietotāju datiem (satur tikai to lietotāju datus, kas ir reģistrēti aplikācijas lietotāji). Ja parametrā padots viens lietotāja ID, tad tiek atgriezti tikai šī lietotāja dati vai `false`, ja tie nav pieejami. Ja parametra vērtība ir `false`, tad atgriezti tiek dati par aktīvo aplikācijas lietotāju.

### 5.16. getUserFriends($page, $limit, $return_ids)

Atgriež lappusi ar aplikācijas lietotāja draugiem, kas arī lieto aplikāciju. Iespējams atgriezt vai nu sarakstu ar lietotāju ID vai arī pilnus lietotāju profila datus.

- **`$page`**: Atgriežamās draugu lappuses numurs, kas jāatgriež (numerācija sākas ar 1)
- **`$limit`**: Vajadzīgais lietotāju skaits vienā lapā (maksimālā atļautā vērtība 200)
- **`$return_ids`**: `true`, ja vajadzīgs atgriezt tikai lietotāju ID vai `false` (noklusētā vērtība), ja vajadzīgi pilni lietotāju dati.
- **Atgriežamā vērtība**: Masīvs ar lietotāja draugu ID vai profila datiem vai `false`, ja pieprasījums nav izdevies.

### 5.17. getAllUserFriends($page, $limit, $return_ids)

Atgriež lappusi ar aplikācijas lietotāja draugiem. Iespējams atgriezt vai nu sarakstu ar lietotāju ID vai arī pilnus lietotāju profila datus. Ja draugs nav aplikācijas lietotājs, tad par viņu pieejama informācija tikai par vārdu, uzvārdu, dzimumu un profila attēlu.

- **`$page`**: Atgriežamās draugu lappuses numurs, kas jāatgriež (numerācija sākas ar 1)
- **`$limit`**: Vajadzīgais lietotāju skaits vienā lapā (maksimālā atļautā vērtība 200)
- **`$return_ids`**: `true`, ja vajadzīgs atgriezt tikai lietotāju ID vai `false` (noklusētā vērtība), ja vajadzīgi pilni lietotāju dati.
- **Atgriežamā vērtība**: Masīvs ar lietotāja draugu ID vai profila datiem vai `false`, ja pieprasījums nav izdevies.

### 5.18. getOnlineFriends($limit, $in_app, $return_ids)

Atgriež sarakstu ar aplikācijas lietotāja draugiem, kas arī lieto aplikāciju un šobrīd ir ienākuši draugiem.lv. Iespējams atgriezt vai nu sarakstu ar lietotāju ID vai arī pilnus lietotāju profila datus.

Funkcija pieejama tikai integrētajām aplikācijām brīdī, kad lietotājs pats atrodas online.

- **`$limit`**: Vajadzīgais lietotāju skaits (maksimālā atļautā vērtība 100)
- **`$in_app`**: `true`, ja vajadzīgs to draugu saraksts, kas tieši šobrīd lieto aplikāciju, `false`, ja vajadzīgs to draugu saraksts, kas atrodas portālā un ir reģistrēti aplikācijas lietotāji.
- **`$return_ids`**: `true`, ja vajadzīgs atgriezt tikai lietotāju ID vai `false` (noklusētā vērtība), ja vajadzīgi pilni lietotāju dati.
- **Atgriežamā vērtība**: Masīvs ar lietotāja draugu ID vai profila datiem vai `false`, ja pieprasījums nav izdevies.

### 5.19. getUserId ()

Atgriež aktīvā lietotāja ID vai `false`, ja tas nav pieejams.

### 5.20. getUserKey ()

Atgriež aktīvā lietotāja API atslēgu vai `false`, ja tā nav pieejama.

### 5.21. getUserLanguage ()

Atgriež aktīvā lietotāja portālā uzstādītajai valodai atbilstošo divu burtu kodu (`lv/ru/en/de/hu/lt`).

### 5.22. imageForSize($img, $size)

Atgriež lietotāja profila attēla adresi vajadzīgajā izmērā.

- **`$img`**: Lietotāja profila attēla adrese standarta izmērā (adrese, kas iegūta no API)
- **`$size`**: Vajadzīgais attēla izmērs (`icon` - 50x50px / `small` - 100x100px / `medium` - 215px plats / `large` - 710px plats)
- **Atgriežamā vērtība**: Lietotāja profila attēla adrese prasītajā izmērā.