“Çorbadan Fıstıklara” Servis API'lerini Kullanan Bir WordPress Eklentisi Yapmak

Gittikçe daha fazla sayıda halka açık API, uygulamalarımızın işlevselliğini genişletmek için güçlü hizmetler sağlar. WordPress, küçük kişisel bloglardan büyük e-ticaret web sitelerine ve aradaki her şeye kadar her şeye güç veren inanılmaz derecede dinamik ve esnek bir CMS'dir. WordPress'i bu kadar çok yönlü yapan şeylerden biri, işlevsellik eklemeyi inanılmaz derecede kolaylaştıran güçlü eklenti sistemidir .

Kısa kodlar kullanarak WordPress sayfalarında GitHub API'sinden veri görüntülemenizi sağlayan bir eklenti olan GitHub Pipeline'ı nasıl yaptığımı anlatacağız. Belirli örnekler ve kod parçacıkları vereceğim, ancak burada açıklanan tekniği bir eklenti ile herhangi bir hizmet API'sinin nasıl tüketileceğine ilişkin bir plan olarak düşünün.

SmashingMag'de Daha Fazla Okuma :

• WordPress Essentials: Bir WordPress Eklentisi Nasıl Oluşturulur
• Geçici Durumları Kullanarak GitHub ile WordPress Eklentileri Nasıl Dağıtılır
• Eklentinize Yapılandırılabilir Alanlar Eklemek İçin Üç Yaklaşım

Baştan başlayacağız, ancak WordPress ve eklenti geliştirme konusunda bir dereceye kadar aşinalık olduğu varsayılıyor ve WordPress veya Composer yüklemek gibi yeni başlayan konulara zaman harcamayacağız.

İhtiyacın olacak:

• WordPress'in yeni kurulumuna sahip bir PHP ortamı;
• bir GitHub hesabı (veya doğaçlama yapmak istiyorsanız başka bir API sağlayıcısı);
• Besteci (önerilir).

API Seçme

Bu tür bir eklenti yazmanın ilk adımı bir API seçmektir. Bu eğitimde GitHub API'sini kullanacağız. Başka bir API kullanmayı düşünüyorsanız, projenizin ne kadar ödüllendirici olacağını etkileyebilecek birkaç önemli faktörü göz önünde bulundurun.

İlk baktığım şeylerden biri, API belgelerinin eksiksizliği ve kalitesi. Seyrek veya eskiyse, kendi sorularınızı yanıtlamak için kaynak kodunu gözden geçirmek için zaman harcamaya hazır olun. Ayrıca, API'nin ne kadar olgun olduğunu ve sağlayıcının onu ne kadar sorumlu bir şekilde sürümlendirdiğini düşünün. Harika bir şey yaratmak için zaman harcamaktan daha kötü bir şey yoktur, yalnızca yukarı akış API'sindeki değişiklikler nedeniyle kırılması için. Uç nokta URL'lerinde bir sürüm oluşturma sistemi arayın.

 // good https://api.stable.com/v1/user/ // danger https://api.dodgy.com/user/

Açık olanı belirtme riskine rağmen, üçüncü taraf bir API'ye karşı programlama bir güven ilişkisi içerir ve tüm API'ler eşit olarak oluşturulmaz.

Kütüphane Alışverişi

Yerleşik markalar, API'leriyle çalışmayı kolaylaştırmak için genellikle kitaplıkları veya SDK'ları dağıtır. Eğer durum böyle değilse, gitmeden önce bir başkasının kitaplık yazıp yazmadığını araştırmayı unutmayın ve tekerleği yeniden icat edin. Google ve GitHub, araştırmanıza başlamak için harika iki yerdir. GitHub'daki yıldızların veya çatalların sayısı, bir kitaplığın ne kadar etkili olduğunun iyi bir göstergesidir. En son taahhütlerin yaşı ve/veya açık konuların sayısı, ne kadar aktif olarak sürdürüldüğünün bir göstergesidir. Benim durumumda, KNP Labs'ın güzel PHP GitHub API'sini bulduğum için şanslıydım.

Guzzle ile Kendi Yazınızı Yazmak

Sağlayıcınız için tatmin edici bir kitaplık yoksa yine de sıfırdan başlamamalısınız çünkü Guzzle gibi araçlar HTTP istekleriyle çalışmayı çok daha kolay hale getirir. Guzzle, PHP'nin cURL kitaplığını sarar ve genellikle manuel olarak istek yapılandırma ve yapma ile ilişkili birçok baş ağrısını ortadan kaldırır. Yalnızca bir veya iki istek yapıyor olsanız bile, kodunuzu daha sağlam hale getireceğinden ve Composer ile yüklemek çocuk oyuncağı olacağından yine de kullanmanızı tavsiye ederim.

Eklentiyi Kurma

İki dosyadan oluşan bir dizin olan minimal bir WordPress eklentisinin temel iskeleti ile başlayacağız. Açıklayıcı ve benzersiz bir klasör adı seçmek, diğer eklentilerle çakışmaları önlemek için önemlidir. Eklentinizin adı biraz genelse, benzersiz bir önek eklemeyi düşünün.

 github-api/ readme.txt github-api.php

readme.txt , eklentiniz için wordpress.org yayınlamaya karar verirseniz görünecek meta verilerini içerir. Belgelerde WordPress eklentileri yayınlama hakkında bilgi edinin veya kapsamlı readme.txt örneğine bakın.

PHP dosyası ayrıca başlıkta eklentiniz hakkında bilgi panosunda görüntülemek için kullanılacak bazı meta verileri içerir. Şuna benzeyen bir başlıkla başlayın:

 <?php /** Plugin Name: GitHub API description: >- Add GitHub project information using shortcode Version: 1.0 Author: Your Name License: GPLv2 or later Text Domain: github-api */

Güvenlik nedenleriyle, aşağıdaki gibi dosyaya doğrudan erişimi reddetmek de iyi bir fikirdir:

 defined( 'ABSPATH' ) or die( 'No script kiddies please!' );

Bu noktada eklenti hiçbir şey yapmayacaktır, ancak dosyaları wp-content/plugins kopyaladığınızda, eklentiler listesinde görünmelidir ve onu etkinleştirebilmelisiniz.

Ardından, API isteklerini işleyecek kitaplığı dahil etmek isteyeceğiz. Aşağıdaki kod örneğinde, KNP Labs'ın PHP GitHub API'sini dahil ediyoruz, ancak kullandığınız paketi knplabs/github-api ile değiştirerek herhangi bir bağımlılığı dahil edebilirsiniz.

 $ cd wp-content/plugins/github-api $ composer require knplabs/github-api

Şimdi, dosya yapınız aşağıdaki gibi görünmelidir:

 github-api/ composer.json composer.lock github-api.php readme.txt vendor/

Artık dosyalar yerinde olduğuna göre, yüklediğiniz zaman oluşturulan vendor/autoload.php dosyasına ihtiyacımız var.

 require_once 'vendor/autoload.php';

Her şey doğru ayarlanmışsa, önemli bir hata atılmadan kütüphaneden bir sınıfı başlatabilmeniz gerekir.

 $testing = new \Github\Client();

Ancak bu, bağımlılıklarınızın kullanılabilir olup olmadığını test etmenin hızlı bir yoludur. Kitaplığı genişleten yeni bir sınıf tanımlamanızı öneririm.

 class MyGithub extends \Github\Client {};

Bu kritik değildir, ancak kodunuzu birkaç şekilde daha esnek hale getirir. En belirgin yol, gerekirse değiştirebilmeniz veya yeni işlevler ekleyebilmenizdir. Ancak gelecekte kitaplıkları değiştirmek istemeniz durumunda hayatı da kolaylaştırır, çünkü değişiklikleri kodunuz boyunca değil, yalnızca bir yerde yapmanız gerekir.

WordPress Kısa Kodları

Şimdi, bir gönderiye veya sayfaya yerleştirerek içerik oluşturmanıza olanak tanıyan özel bir snippet olan ilk kısa kodumuzu oluşturma zamanı. Kısa kodlar konusunda tamamen yeniyseniz veya nasıl çalıştıkları hakkında daha derin bir anlayış istiyorsanız, resmi kısa kod belgelerine bakın. Örneğimde, yazarın bu kısa kodu yerleştirdiği her yerde GitHub sorunlarının bir listesini görüntüleyeceğim: [github_issues]

Daha önce yaptığımız gibi, API çağrısı yapmaya çalışmadan önce kısa kodun doğru şekilde kaydedildiğinden emin olmak için minimal bir örnekle başlayalım.

 function github_issues_func( $atts ) { return "Hello world!"; } add_shortcode( "github_issues", "github_issues_func" );

Şimdi, [github_issues] içeren bir sayfa yayınlarsanız, sayfayı ziyaret ettiğinizde “Merhaba dünya” görmelisiniz. Şimdi bu çalıştığına göre, API çağrısını ayarlayalım.

Bir önceki bölümde GitHub kitaplığımız için otomatik yüklemeyi kurduk ve onu genişletmek için kendi sınıfımızı tanımladık. Artık API çağrıları yapmak için kullanmaya başlayabiliriz. Bu yüzden, onu kısa kodun geri arama işlevine ekleyeceğiz. Kavram kanıtı olarak, GitHub Pipeline deposundaki tüm sorunları getirelim. Bu yöntem için belgeler mevcuttur.

 function github_issues_func( $atts ) { // Instantiate our class $gh = new MyGithub(); // Make the API call to get issues, passing in the GitHub owner and repository $issues = $gh->api('issue')->all('TransitScreen', 'wp-github-pipeline'); // Handle the case when there are no issues if ( empty($issues) ) return "<strong>" . __("No issues to show", 'githup-api') . "</strong>"; // We're going to return a string. First, we open a list. $return = "<ul>"; // Loop over the returned issues foreach( $issues as $issue ) { // Add a list item for each issue to the string // (Feel free to get fancier here) // Maybe make each one a link to the issue issuing $issue['url] ) $return .= "<li>{$issue['title']}</li>"; } // Don't forget to close the list $return .= "</ul>"; return $return; } add_shortcode( 'github_issues', 'github_issues_func' );

Şimdi, yukarıda kısa kodu test etmek için kullandığımız aynı sayfayı görüntüleyebilmelisiniz ve bu sefer sırasız bir sorun listesi görmelisiniz. Fakat bekle! Devam etmeden önce, kodumuzun test edilmesinin daha kolay olması için bir optimizasyon yapalım. (Test ediyorsun değil mi?!) GitHub kitaplık sınıfını somutlaştırmak için fonksiyonumuzda new kullanmak yerine, onu bir parametre olarak aktaralım ve sadece mecbur kalırsak somutlaştıralım.

 function github_issues_func( $atts, $gh=null ) { // Conditionally instantiate our class $gh = ( $gh ) ? $gh : new MyGithub(); …

Bu değişiklik, fonksiyonumuzun test edilmesini çok daha kolay hale getiren bağımlılık enjeksiyon modeline benzer. WordPress birim testi, bu öğreticinin kapsamı dışındadır, ancak bu yeni sürümün, "sahte" API verilerini işleve geçirmemizi nasıl kolaylaştırdığını görmek kolaydır, böylece testimizin iddiaları tam olarak ne bekleneceğini bilir.

Şimdiye kadar yaptıklarımız, yalnızca tek bir havuzda kullanılacak bir dahili proje için iyi ve iyidir, ancak kullanıcıların sorunları hangi havuzdan alacaklarını yapılandırabilmeleri çok daha faydalı olacaktır. Bunu ayarlayalım.

İlk olarak, yeni ayarlar sayfamızı kaydetmek için bir WordPress kancası kullanacağız ve geri arama işlevi menünün etiketlerini ve başlıklarını tanımlayacaktır. Çalışmasını sağlamak için aynı artımlı yaklaşımı kullanacağız.

 // Register the menu. add_action( "admin_menu", "gh_plugin_menu_func" ); function gh_plugin_menu_func() { add_submenu_page( "options-general.php", // Which menu parent "GitHub", // Page title "GitHub", // Menu title "manage_options", // Minimum capability (manage_options is an easy way to target administrators) "github", // Menu slug "gh_plugin_options" // Callback that prints the markup ); } // Print the markup for the page function gh_plugin_options() { if ( !current_user_can( "manage_options" ) ) { wp_die( __( "You do not have sufficient permissions to access this page." ) ); } echo "Hello world!"; }

Şimdi kontrol paneline giriş yapabilmeli ve "Ayarlar" altındaki yeni GitHub menüsünü görebilmeli ve ardından "Merhaba dünya!" yazan boş bir ayarlar sayfasını görmek için tıklamalısınız.

Ardından, Hello word formun gerçek işaretlemesiyle değiştireceğiz. Size istediğiniz kadar az veya çok stil uygulayabileceğiniz bir barebone örneği vereceğim.

 ?> <form method="post" action="<?php echo admin_url( 'admin-post.php'); ?>"> <input type="hidden" name="action" value="update_github_settings" /> <h3><?php _e("GitHub Repository Info", "github-api"); ?></h3> <p> <label><?php _e("GitHub Organization:", "github-api"); ?></label> <input class="" type="text" name="gh_org" value="<?php echo get_option('gh_org'); ?>" /> </p> <p> <label><?php _e("GitHub repository (slug):", "github-api"); ?></label> <input class="" type="text" name="gh_repo" value="<?php echo get_option('gh_repo'); ?>" /> </p> <input class="button button-primary" type="submit" value="<?php _e("Save", "github-api"); ?>" /> </form> <?php

Dahil ettiğim CSS sınıfları, WordPress'in çekirdeği tarafından kullanılanlarla eşleşir; bu, özel seçenekler sayfanızın ek bir çaba harcamadan düzgün görünmesini sağlamanın güzel bir yoludur.

Bu form hakkında anlaşılması gereken iki önemli şey var. İlk olarak, gönderdiği uç nokta /wp-admin/admin-post.php olmalıdır. Bu yolu sabit kodlayabilirsiniz, ancak web sitesi bir alt dizine kuruluysa çalışmayacaktır. Bu nedenle, dinamik olarak oluşturmak için yerleşik admin_url() kullanıyoruz.

İkinci olarak, action adındaki gizli girdiye dikkat edin. Bu alan, WordPress'in form tarafından gönderilen gönderi isteğiyle ne yapacağını nasıl bildiğidir. value , geri arama işlevini ayarlamak için kullanacağımız eylem kancasının adına karşılık gelir. Bağlanacağımız eylemin adı, admin post ile ön eki olan bu değer olacaktır. Yani, bizim durumumuzda şunu eklememiz gerekiyor:

 add_action( 'admin_post_update_github_settings', 'github_handle_save' );

Bunu, özel yönetim menüleri oluşturmanın daha tuhaf, daha az sezgisel yönlerinden biri olarak görüyorum, ancak bir kez alışınca, oldukça acısız. Tahmin edebileceğiniz gibi, add_action() ikinci parametresi, değerleri gerçekten veritabanına kaydedecek olan geri çağırma işlevimizin adıdır.

 function github_handle_save() { // Get the options that were sent $org = (!empty($_POST["gh_org"])) ? $_POST["gh_org"] : NULL; $repo = (!empty($_POST["gh_repo"])) ? $_POST["gh_repo"] : NULL; // Validation would go here // Update the values update_option( "gh_repo", $repo, TRUE ); update_option("gh_org", $org, TRUE); // Redirect back to settings page // The ?page=github corresponds to the "slug" // set in the fourth parameter of add_submenu_page() above. $redirect_url = get_bloginfo("url") . "/wp-admin/options-general.php?page=github&status=success"; header("Location: ".$redirect_url); exit; }

Örnek de oldukça azdır. Bir üretim ortamında, muhtemelen bir miktar doğrulama eklemek istersiniz. Ayrıca, bu örnekte, URL'ye status=success otomatik olarak geri iletiyoruz. Formun işaretlemesi aslında onu henüz kullanmıyor. Bir başarı mesajını koşullu olarak göstermek için, formun yukarısına gh_plugin_options() içinde aşağıdakine benzer bir şey ekleyin:

 if ( isset($_GET['status']) && $_GET['status']=='success') { ?> <div class="updated notice is-dismissible"> <p><?php _e("Settings updated!", "github-api"); ?></p> <button type="button" class="notice-dismiss"> <span class="screen-reader-text"><?php _e("Dismiss this notice.", "github-api"); ?></span> </button> </div> <?php }

Doğrulama eklerseniz, kullanıcının formu göndermesinin başarısız olup olmadığını ve neden başarısız olduğunu bilmesi için farklı durumları ve mesajları geri iletmek için aynı kalıbı kullanın.

Artık yeni sahip ve depo değerlerini kaydedebilmelisiniz. GitHub'daki herhangi bir genel projenin sahibini ve deposunu girerek test edin. Son adım, github_issues_func() kod geri çağırma işlevine geri dönmek ve sabit kodlanmış sahip ve depo değerlerini değiştirmektir.

 … $issues = $gh->api("issue")->all(get_option("gh_org"), get_option("gh_repo")); …

Bu yerleştirildikten sonra, kısa kodu eklediğiniz sayfayı tekrar ziyaret edin. Artık belirlediğiniz projeden sorunları görmelisiniz.

Bonus Turu: OAuth 2.0 Kimlik Doğrulaması

Yukarıda kullandığımız yaklaşım, genel depolar için harika çalışıyor, ancak bu eklentiyi kimlik doğrulama gerektiren özel bir depoyla kullanmak istiyorsak ne olur? GitHub API, bugünlerde en popüler API'lerle çalışırken karşılaşacağınız OAuth 2.0 protokolünü kullanarak kimlik doğrulaması yapar. Temel OAuth 2.0 iş akışı şu şekildedir:

1. Sağlayıcıya bir uygulama (bazen "istemci" olarak adlandırılır) kaydedersiniz ve benzersiz bir kimlik ve gizli anahtar alırsınız.
2. Uygulamanız, sağlayıcının kimlik doğrulama uç noktasına bir istekte bulunur ve yukarıdaki kimlik bilgilerinin yanı sıra sağlayıcının isteği uygulamanızın bir uç noktasına yeniden yönlendirmek için kullandığı bir yönlendirme URL'sini iletir.
3. Daha sonra kullanıcıdan erişim isteğinizi kabul etmesi istenir. Bunu yaparlarsa, sağlayıcı, kullanıcıyı geçici bir kodla birlikte uygulamanıza geri yönlendirmek için istekle birlikte gönderdiğiniz URL'yi kullanır.
4. Uygulamanız bu kodu yakalar ve ardından ikinci bir istekte bulunur ve bu kodu sağlayıcıya geri iletir. Sağlayıcı, uygulamanızın daha sonra sağlayıcıyla kimlik doğrulaması yapmak için kullandığı bir erişim belirteci ile yanıt verir.

GitHub'a bir uygulama kaydederek başlayacağız. En popüler API'lerde olduğu gibi, bu bölüm web sitesinin geliştirici alanında bulunur.

Buradaki en önemli şey, yetkilendirme geri arama URL'sidir. Üçüncü adımda iletilen yönlendirme URL'si, buraya girdiğiniz ile eşleşmeli veya onu içermelidir. Bu nedenle, geliştirme sırasında genellikle web sitesinin ana sayfasına girerim. Bu şekilde, uygulamam herhangi bir yola yönlendirebilir.

Ardından, uygulamanın istemci kimliğini ve sırrını göndermek için gh_plugin_options() içindeki ayarlar sayfamıza ikinci bir form ekleyeceğiz.

 <form method="post" action="<?php echo admin_url( 'admin-post.php'); ?>"> <input type="hidden" name="action" value="oauth_submit" /> <h3>Oauth 2.0</h3> <p> <label><?php _e("GitHub Application Client ID:", "github-api"); ?></label> <input class="" type="text" name="client_id" value="<?php echo get_option('client_id')?>" /> </p> <p> <label><?php _e("GitHub Application Client Secret:", "github-api"); ?></label> <input class="" type="password" name="client_secret" value="<?php echo get_option('client_secret')?>" /> </p> <input class="button button-primary" type="submit" value="<?php _e("Authorize", "github-api"); ?>" /> </form>

Hayatı kolaylaştırmak için, The League of Extraordinary Packages'in OAuth 2.0 İstemcisi için GitHub Sağlayıcısını kullanacağım. İlk olarak, bağımlılığı eklemek için Composer'ı tekrar kullanalım:

 composer require league/oauth2-github

KNP Labs'in GitHub kitaplığının da yerleşik OAuth 2.0 desteğine sahip olduğunu unutmayın. Bu nedenle, benim özel örneğimde bu biraz gereksiz. Ancak bu kitaplığı tanıtmak istedim çünkü hepsi güçlü League of Extraordinary Packages tarafından sağlanan aynı çerçeveyi genişleten sağlayıcıya özel OAuth 2.0 istemci kitaplıkları grubuna ait. Desteklenen sağlayıcıların tam listesini görüntüleyebilir veya yeni bir sağlayıcıyı desteklemek için çerçevenin nasıl genişletileceğine ilişkin talimatları okuyabilirsiniz.

Kullanıcı formu gönderdiğinde belirteci istemek ve kaydetmek için bir işlev oluşturalım. GitHub zaten desteklenen sağlayıcılardan biri olduğundan, örneğini belgelerine yalnızca birkaç değişiklikle kopyalayabilirim.

 function handle_oauth() { // If the form was just submitted, save the values // (Step 1 above) if ( isset($_POST["client_id"]) && isset($_POST["client_secret"]) ) { update_option( "client_id", $_POST["client_id"], TRUE ); update_option("client_secret", $_POST["client_secret"], TRUE); } // Get the saved application info $client_id = get_option("client_id"); $client_secret = get_option("client_secret"); if ($client_id && $client_secret) { $provider = new League\OAuth2\Client\Provider\Github([ "clientId" => $client_id, "clientSecret" => $client_secret, "redirectUri" => admin_url("options-general.php?page=github"), ]); } // If this is a form submission, start the workflow // (Step 2) if (!isset($_GET["code"]) && $_SERVER["REQUEST_METHOD"] === "POST") { // If we don't have an authorization code, then get one $authUrl = $provider->getAuthorizationUrl(); $_SESSION["oauth2state"] = $provider->getState(); header("Location: ".$authUrl); exit; // Check given state against previously stored one to mitigate CSRF attack // (Step 3 just happened and the user was redirected back) } elseif (empty($_GET["state"]) || ($_GET["state"] !== $_SESSION["oauth2state"])) { unset($_SESSION["oauth2state"]); exit("Invalid state"); } else { // Try to get an access token (using the authorization code grant) // (Step 4) $token = $provider->getAccessToken("authorization_code", [ "code" => $_GET["code"] ]); // Save the token for future use update_option( "github_token", $token->getToken(), TRUE ); } }

Ve tıpkı diğer formda yaptığımız gibi, form kaydedildiğinde işlevin çağrılması için eylem kancasını eklememiz gerekiyor.

 add_action( "admin_post_oauth_submit", "handle_oauth" );

Formu kaydetmek şimdi sizi API sağlayıcısının yetkilendirme sayfasına göndermelidir. Yetkilendirmeden sonra uygulamanız, erişiminiz olan özel havuzlardan veri istemek için kaydedilen belirteci kullanabilir. KNP Labs tarafından kullandığım kitaplığın bunun için kullanışlı bir yöntemi var.

 $gh = new MyGithub(); $gh->authenticate( get_option("github_token"), NULL, Github\Client::AUTH_HTTP_TOKEN);

Kitaplıklar, kimlik doğrulamayı tam olarak nasıl ele aldıklarına göre farklılık gösterecektir, ancak bir şekilde, bir kullanıcı adına kimliği doğrulanmış istekler yapacak olan belirteci ileteceksiniz.

Çözüm

Çok fazla yol kat ettik ve genel iş akışının net kalması için örnekleri mümkün olduğunca az tutmaya çalıştım. Bu eğitimdeki tam kaynak kodu mevcuttur. Umarım artık üçüncü taraf hizmet API'lerini tüketen bir WordPress eklentisi oluşturmayla ilgili hareketli parçaları net bir şekilde anlamışsınızdır ve umarım kendi WordPress API eklentinizi yazmak için ilham alırsınız.

Son Notlar

• WordPress Kodeksi (belgeler)
• GitHub API (belgeler)
• OAuth 2.0 (belgeler)
• Besteci (belgeler)
• Olağanüstü Paketler Ligi
• Guzzle Dokümantasyonu