ondrakoupil/hybridauth-skautis

Plugin pro HybridAuth umožňující jednoduché přihlašování přes SkautIS.

Jednoduché přihlašování přes SkautIS pomocí HybridAuth

HybridAuth je PHP knihovna pro univerzální přihlašování přes různé veřejné služby a sociální sítě, např. Facebook či Google. S pomocí tohoto rozšíření lze do vaší aplikace přidat i přihlašování přes SkautIS., _(*1)

Instalace

Pokud ve své aplikaci používáte Composer, nainstalujete jednoduše:, _(*2)

composer require ondrakoupil/hybridauth-skautis, _(*3)

Pokud nepoužíváte Composer, je třeba si zkopírovat soubory z adresáře src a libovolným způsobem je všechny includovat. Samotný HybridAuth lze stáhnout z jeho webu., _(*4)

Použití

Přihlášení přes SkautIS probíhá až na několik odlišností stejně jako přes Google či Facebook. Pokud s HybridAuth nemáte zkušenosti, prostudujte si jejich dokumentaci, kde je vše dopodrobna popsané., _(*5)

Anebo si přečtěte stručný návod pro začátky s HybridAuthem, který vás namíří správným směrem., _(*6)

Také budete potřebovat svoji aplikaci zaregistrovat do SkautISu a získat její AppID., _(*7)

Nastavení

V konfiguraci HybridAuth přidáte nový provider jménem SkautIS. Konfigurace může vypadat zhruba takto:, _(*8)

$config = array(
    "base_url" => "... URL vašeho endpointu ...",
    "providers" => array (
        "SkautIS" => array(
            "enabled" => true,
            "test" => true,
            "wrapper" => array(
                "class" => "\\HybridAuth\\SkautIS\\Adapter"
            ),
            "keys" => array(
                "appId" => "... vaše APP ID ..."
            ),
            "data" => array(
                "contacts" => true,
                "photo" => true,
                "roles" => true,
                "unit" => true,
                "roleUnitDetails" => false
            ),          
            "photoProxy" => "",
            "photoSize" => "medium"
        ),
        "Google" => "...",
        "Facebook" => "...",
        "Twitter" => "..."
    )
);

Nyní blíže k jednotlivým položkám:, _(*9)

• test = true nebo false podle toho, zda chcete používat testovací SkautIS anebo ostrý. Výchozí hodnota je true (tj. testovací). Po přechodu na ostrý nezapomeňte změnit i AppID.
• wrapper = zde je nutno zadat jméno třídy včetně namespaců (tj. \HybridAuth\SkautIS\Adapter), pokud si soubor s třídou Adapter nenakopírujete mezi ostatní adaptéry do adresáře se zdrojáky HybridAuthu.
• keys = array s jedinou položkou appId. Nezapomeňte, že se liší pro testovací a ostrý SkautIS.
• data = nepovinné array umožňující upřesnit, co všecno ze SkautISu potřebujete vytáhnout a případně tak zrychlit přihlášení tím, že zakážete nepotřebné údaje. Ve výchozím nastavení zapnuté vše kromě roleUnitDetails
  • contacts = další kontakty jako telefon či web (kromě e-mailu, ten je vždy součást základních dat)
  • photo = profilová fotka uživatele
  • roles = seznam všech rolí uživatele
  • unit = podrobnosti o jednotce (oddílu, středisku...), ve kterém je uživatel registrován
  • roleUnitDetails = podrobnosti o všech jednotkách, ve kterých má uživatel nějakou roli
• photoProxy = nepovinné, viz níže
• photoSize = nepovinná požadovaná velikost fotky: small, medium, normal, big

Rozdíly oproti standardnímu přihlášení přes HybridAuth

Jelikož SkautIS je dost specifický a pravděpodobně z něj budete chtít i nějaká jiná data, než HybridAuth vydoluje z klasických sociálních sítí, tak volání $adapter->getUserProfile() nevrací standardní Hybrid_User_Profile, ale jeho odděděnou rozšířenou verzi, objekt třídy \HybridAuth\SkautIS\UserProfile. Ten obsahuje jak to, co základní profil, tak i nějaké další údaje navíc specifické pro SkautIS týkající se zejména rolí a jednotek v Junáku. Je na vás, jak si s nimi pak ve své aplikaci poradíte., _(*10)

Prohlédněte si třídy UserProfile, Role a Unit, z nichž jistě vše pochopíte podrobněji., _(*11)

Fotky

HybridAuth předpokládá, že poskytovatel přihlášení nabízí ke stažení uživatelův portrét jako na nějaký URL, který lze získat přes UserProfile -> $photoURL. SkautIS ale posílá přímo binární obsah obrázku. Ten je sice dostupný v UserProfile -> $photoData, ale abychom zachovali kompatibilitu s ostatními poskytovateli, lze nastavit v konfiguraci položku photoProxy, která práci s obrázky sjednotí. Zvolte si takový přístup, který bude lépe vyhovovat dalšímu zpracování obrázků po přihlášení., _(*12)

photoProxy může být buď obyčejný string, který představuje cestu k nějakému adresáři. Po přihlášení se v tomto adresáři vytvoří soubor s obrázkem a $photoURL se nastaví na cestu k němu. Tato cesta bude dostupná jen lokálně. Po jeho zpracování byste pak tento soubor zase měli smazat., _(*13)

Druhou možností je zadat array se dvěma položkami, dir a url. dir je stejně jako v předchozím případě cesta k adresáři pro uložení souboru a url je jeho veřejná URL adresa, přes níž je možné se na soubory v adresáři dostat přes internet. $photoURL se pak nastaví na veřejný URL vzniklého souboru., _(*14)

"photoProxy" => "../some/temp/directory"

"photoProxy" => array(
    "dir" => "../www/portraits",
    "url" => "http://www.moje-aplikace.cz/portraits"
)

Ladění chyb

Pokud něco nefunguje, lze zapnout standardní debug režim v HybridAuth. Stačí do konfigurace přidat:, _(*15)

"debug_mode" => true,
"debug_file" => "cesta_k_souboru/kam_se_bude/logovat.txt"

Do tohoto logu se pak kromě ostatních informací o průběhu zpracování bude zapisovat i komunikace se SkautISem, každá volaná metoda a návratová hodnota., _(*16)

Pomoc, podpora, hlášení chyb atd.

Pokud jste narazili na jakoukoliv potíž nebo vám něco není jasné, přidejte issue zde na GitHubu, anebo mi napište přímo. Pokusím se poradit, bude-li to v mých silách :-), _(*17)