Открытая Yandex PHP Library для работы с API Яндекса

AntonShevchuk 30 июля 2014 в 15:04 59,5k
Привет всем!

Давненько я не писал на Хабр. Не то что бы мне не о чем было рассказывать, просто если уж и делиться историями, то такими, чтобы зуд появлялся работать до полуночи. Тем более, если они будут о сотрудничестве PHP-разработчиков и Яндекса. Тем более, если они о том, что появилась долгожданная PHP-библиотека для работы с API Яндекса.



Расскажу-напомню немного о себе. Меня зовут Антон Шевчук. На Хабре я довольно давно, и если вы изучали jQuery, то с большой долей вероятности читали и мой блог. При этом моя основная активность — это всё же PHP-разработка, да и должность обязывает — работаю я техническим экспертом PHP-отдела в компании NIX Solutions.

Но хватит лирики, я же обещал познавательную историю.

Началась она в 2008-м году с написания PHP-библиотеки для работы с сервисом Яндекс.XML, библиотеку я скромно именовал yandex-xml и старался её поддерживать. Фактически я взял на себя часть обязанностей поддержки Яндекса, но, думаю, это их не сильно огорчило. Конечно же, я задавался вопросом: «А где, собственно, родная библиотека от Яндекса?» Кто ж знал, что ответ я узнаю спустя пять лет :)

Время шло, у Яндекса появлялись всё новые и новые сервисы, а где есть сервисы, там есть и API. Они плодились и размножались, а удобного инструмента для PHP-разработчиков всё как-то не появлялось. При этом интерес к сервисам продолжал расти, и уже из праздного любопытства перерос в профессиональный.

Год назад в период летнего обострения перфекционизма терпение лопнуло, и моя компания обратилась в Яндекс с предложением написать php-библиотеку для всех API Яндекса. Нам требовалась помощь в ответах на многочисленные вопросы, а также наставления от команд тех или иных API, лучше понимающих, как их сервис устроен и как работает. Одним из аргументов был как раз пример с библиотекой yandex-xml, и её счётчик загрузок переваливший за пару тысяч.

Дмитрий Вульбрун, один из менеджеров Яндекса, вызвался нам помогать, связывать с разными отделами/группами/сервисами и упрощать общение с различными командами.

Я позволю себе вставить здесь его комментарий по этому поводу.

Исторически сложилось так, что в Яндексе нет php. Вообще нет. Мы понимаем боль разработчиков, пытающихся использовать наши технологии на своих сайтах, но возможности развернуть большую инфраструктуру внутри компании для создания такой библиотеки у нас нет. Для этого нужны машины, админы, php-разработчики, тестировщики, технические писатели, саппорт. В конце концов, нужен и менеджер этого проекта. Технически это, конечно, реализуемо, и мы даже пытались создать такую инфраструктуру внутри Яндекса для разработки своей SDK-php, но вскоре поняли, что до этого совсем не доходят руки. Мы пытались создавать подобные вещи и на аутсорсе, но поддерживать все это потом все равно приходится самим. А у нас оказалось не так много людей, знающих php и различные CMS. Поэтому нам очень понравилась идея создания библиотеки снаружи компании — силами людей, имеющих готовую инфраструктуру для этого и понимающих веб-мастеров и веб-разработчиков. Конечно же, мы всячески поддерживаем это начинание.


А дальше мы начали работу. Определили требования.

  • Развивать подобную библиотеку силами лишь одной команды — не самый лучший вариант, а вот организовать комьюнити из единомышленников это куда как веселее. Тем более, что таким образом количество проблем в коде будет уменьшаться обратно пропорционально скилам всей команды, поэтому первым требованием стало — opensource проект и сообщество.
  • Очень хотелось стартовать разработку с поддержки PHP версии 5.4, но нужно было покрыть как можно большую аудиторию, да и PHP сообщество всё ещё поддерживает более старую версию, как итог терзаний — поддержка версии 5.3
  • Отдельно выделю повышенные требования к юзабилити кода — этакая моя личная блажь
  • И еще — повышенные требования к качеству кода — тесты, стандарты и т.д.


Путь для развития был задан, оставались технические тонкости. Нужно было понять, как мы будем давать возможность подключать библиотеку. Сначала решили, что Composer — лучшее и единственно правильное решение: современно, вкусно, аппетитно. Однако не всем веб-разработчикам подходит данный вариант, поэтому было решено совместить composer с phar-архивами как с более простым способом интеграции, хотя и со своими заморочками.

Выбор порядка, в котором нужно писать модули для библиотеки, оставался за Яндексом. И я еще раз процитирую Дмитрия:

Когда мы с Антоном начали обсуждать создание библиотеки, первым делом было для меня собрать воедино всю информацию обо всех API Яндекса. Это было не так просто, как казалось на первый взгляд, и заняло немало времени — Яндекс большой :)
Все команды по-разному реагировали на нашу идею: кто-то загорался этим сразу, кто-то более спокойно относился к нашей затее. К тому же, некоторые команды планировали переделывать или выпускать новые версии к своим API, и писать в этом случае библиотеку нужно было уже для новых, пока не вышедших в продашкен, версий API.

В целом, конечно, все понимали, что общая php-библиотека для работы со всеми API Яндекса — это нужная вещь и мы «сделаем мир лучше». Нужно было решить, с чего начать.

Так как я занимаюсь сервисом Поиск для сайта, и у него есть одна маленькая и простая ручка API, мы решили оформить проект на гитхабе и разработать инфраструктуру для разработки библиотеки, создав модуль именно для Поиска для сайта. Это логично: работу всегда проще начинать с чего-то более простого.
Далее мы проанализировали имеющиеся сведения про все наши API. Выяснили, что большинство из них имеет авторизацию на OAuth, поэтому следующим шагом было создание отдельного модуля для авторизации. Чтобы потом этот модуль можно было использовать дальше.

Ну, а дальше порядок сервисов обуславливался в основном активностью команды конкретного сервиса и желанием ее участников помогать коллегам из NIX Solutions и направлять их в создании библиотеки. Так мы получили первый список: Safe Browsing API, API Диска, Покупка на Маркете, API Метрики.


Итак, по мере предоставления нам информации от команд Яндекса пилились и модули, не без багов, но работа шла.

На сегодняшний день библиотека уже подросла и включает в себя несколько модулей:
  • Модуль авторизации OAuth
  • Модуль для пингера сервиса Поиск для сайта
  • Модуль для Safe Browsing API
  • Модуль для API Яндекс.Диска (WebDAV)
  • Модуль для «Покупки на Маркете» в рамках Партнерского API Маркета

О каждом модуле я скажу буквально пару фраз, без технических подробностей. Все подробности мы выложили на GitHub.

Модуль авторизации OAuth
Один из первых разработанных модулей — это авторизация на сервисах Яндекcа API. На текущий момент времени сервисы Яндекса в основном используют OAuth авторизацию, что очень сильно облегчает работу с оными, а с нашей библиотекой работа становится ещё проще. Документация.


Модуль для пингера сервиса Поиск для сайта
Если на своём сайте вы используете сервис Поиск для сайта, то вам стоит обратить внимание на библиотеку пингер, задача которой — информировать Яндекс о новых и измененных документах на сайте. Документация.


Модуль для Safe Browsing API
Данный пакет отвечает за проверку URL на причастность к неблагонадёжным сайтам, чтобы часом никакая зараза к вам не пристала. Данный сервис пригодится для сайтов, на которых размещаются ссылки на другие ресурсы в сети. Документация.


Модуль для API Яндекс.Диска (WebDAV)
Яндекс.Диск уверенно набирает очки как альтернатива различным драйвам, и, я надеюсь, данная библиотека послужит ещё одним шагом в завоевывании рынка. Документация.


Модуль для «Покупки на Маркете» в рамках Партнерского API Маркета
Если ваш магазин размещает предложения на Яндекс.Маркете, то стоит обратить внимание на соответствующую библиотеку. Документация.


Сейчас идёт разработка модуля для работы с API Метрики.

Инфраструктура разработки


Мы не только делаем библиотеку, но и обзаводимся удобствами для разработки и тестирования. GitHub уже давно стал для многих платформой для разработки «по умолчанию». Он успел обрасти приятными плюшками, которые можно прикрутить к проекту в пару кликов или в пару строчек, и я хотел остановиться на них чуть-чуть поподробнее.

Travis CI

Для подключения сервиса непрерывной интеграции Travis вам потребуется создать конфигурационный файл (можно за основу взять наш) и подключить свой проект на GitHub'е на сайте travis-ci.org.

На данный момент на плечи Travis ложится прогонка юнит-тестов и стандартов PSR на различных версиях PHP (включая даже HHVM и версию PHP 5.6), а так же создания phar архива с дальнейшим аплоадом оного на Яндекс.Диск с использованием нашей же библиотеки :)

Подробнее о Travis CI уже было рассказано на Хабре — habrahabr.ru/post/140344

Результат интеграции доступен здесь

Scrutinizer CI

Ещё один инструмент для контроля качества кода, позволяет выявить потенциальные проблемы и даёт рекомендации по улучшению (можете прям патчиком, остаётся скопировать и применить). Основная часть работы ложится на PHP_Analyzer, но не им единым.

Результат интеграции проекта — scrutinizer-ci.com/g/nixsolutions/yandex-php-library

Coveralls

Это простая тулза, которая сохраняет информацию о покрытии тестами вашего проекта. Для тех, кто знаком с phpunit, — это визуализация clover.xml с трекингом изменений. За аплоад данных отвечает Travis, для работы требуется установить пакет «satooshi/php-coveralls» и конфигурационный файл по примеру — github.com/nixsolutions/yandex-php-library/blob/master/.coveralls.yml

Результат: coveralls.io/r/nixsolutions/yandex-php-library

И ещё немного «значков» для коллекции можно заполучить на сайте poser.pugx.org.

Вместо заключения


… И чтобы избежать в комментариях картинки с троллейбусом из буханки хлеба.

Профит для компании NIX Solutions — пиар нашего сотрудничества с компанией Яндекс (собственно это уже третье упоминание названия компании в данной статье :). Плюс мы обзавелись нехилым knownledge base по API и можем помочь PHP разработчикам ответить на часто задаваемые вопросы по интеграции сервисов Яндекса.

Профит для Яндекса — разработка библиотеки для огромного PHP-комьюнити силами PHP-разработчиков. Отчасти перекладывание поддержки на наши плечи.

Профит для комьюнити — теперь у нас есть актуальная библиотека для работы с сервисами Яндекса, при этом в развитии оной может поучаствовать каждый разработчик

Так что, дорогой Хабр, не стесняйся и присылай свои вопросы, а лучше pull-запросы на GitHub — github.com/nixsolutions/yandex-php-library.

Ждём, целуем, любим.
Проголосовать:
+111
Сохранить: