Open Yandex PHP Library for working with Yandex API

    Hello everybody!

    A long time ago I did not write on Habr. Not that I had nothing to tell about, just if I were to share stories, then such that the itch appeared to work until midnight. Especially if they will be about the collaboration of PHP developers and Yandex. Especially if they are talking about the long-awaited PHP library for working with the Yandex API . I’ll tell you, let’s remind you a little about myself. My name is Anton Shevchuk. I was on Habré for a long time, and if you studied jQuery, then with a high degree of probability you also read my blog . At the same time, my main activity is still PHP development, and the position is obligatory - I work as a technical expert in the PHP department at NIX Solutions . But enough lyrics, I promised an informative story.

    It began in 2008 with writing a PHP library to work with the Yandex.XML service , I modestly called the library yandex-xml and tried to maintain it. In fact, I took on part of the responsibilities of supporting Yandex, but I think this did not upset them much. Of course, I wondered: “And where, in fact, is the native library from Yandex?” Who knew that I’ll find out the answer five years later :)

    Time passed, Yandex got more and more new services, and where there are services, there is also an API. They multiplied and multiplied, but somehow there wasn’t any convenient tool for PHP developers. At the same time, interest in services continued to grow, and already out of idle curiosity grew into a professional.

    A year ago, during the summer aggravation of perfectionism, patience was over, and my company turned to Yandex with a proposal to write a php library for all Yandex APIs. We needed help in answering numerous questions, as well as instructions from teams of various APIs who better understand how their service works and how it works. One of the arguments was just an example with the yandex-xml library, and its download counter exceeded a couple of thousand.

    Dmitry Vulbrun, one of Yandex managers, volunteered to help us, connect with different departments / groups / services and simplify communication with different teams.

    I allow myself to insert his comment on this subject here.

    Historically, Yandex has no php. Absolutely not. We understand the pain of developers trying to use our technologies on their sites, but we do not have the opportunity to deploy a large infrastructure within the company to create such a library. For this we need machines, admins, php developers, testers, technical writers, support. In the end, you need a project manager. Technically, this, of course, is feasible, and we even tried to create such an infrastructure inside Yandex to develop our SDK-php, but soon realized that our hands weren’t getting at all. We tried to create similar things and outsource, but then we still have to support all this ourselves. And we didn’t have so many people who know php and various CMS. Therefore, we really liked the idea of ​​creating a library outside the company - through the efforts of people, having a ready-made infrastructure for this and understanding webmasters and web developers. Of course, we strongly support this initiative.

    And then we started work. Defined requirements.

    • Developing such a library with the help of only one team is not the best option, but organizing a community of like-minded people is much more fun. Moreover, in this way the number of problems in the code will decrease inversely with the skills of the whole team, so the first requirement was an open source project and community.
    • I really wanted to start development with support for PHP version 5.4, but it was necessary to cover the largest possible audience, and the PHP community still supports the older version, as a result of torment - support for version 5.3
    • Separately, I highlight the increased requirements for the usability of the code - a sort of my personal whim
    • And yet - increased requirements for code quality - tests, standards, etc.

    The path for development was set, technical subtleties remained. It was necessary to understand how we will give the opportunity to connect the library. At first they decided that Composer was the best and only right decision: modern, tasty, appetizing. However, this option is not suitable for all web developers, so it was decided to combine composer with phar archives as an easier way to integrate, although with their own troubles.

    The choice of the order in which to write modules for the library remained with Yandex. And I will quote Dmitry again:

    When Anton and I started discussing the creation of the library, the first thing for me was to put together all the information about all Yandex APIs. It was not as simple as it seemed at first glance, and it took a lot of time - Yandex big :)
    All the teams reacted differently to our idea: someone caught fire right away, someone more relaxed about our venture. In addition, some teams planned to redo or release new versions of their APIs, and in this case, the library needed to be written for new, not yet released, versions of the API.

    In general, of course, everyone understood that a common php library for working with all Yandex APIs is the right thing and we will "make the world a better place." It was necessary to decide where to start.

    Since I am engaged in the Search service for the site, and it has one small and simple API handle, we decided to place the project on the github and develop the infrastructure for developing the library, creating a module specifically for Search for the site. This is logical: it is always easier to start work with something simpler.
    Next, we analyzed the available information about all our APIs. We found out that most of them have OAuth authorization, so the next step was to create a separate module for authorization. So that later this module can be used further.

    Well, and then the order of services was mainly determined by the activity of the team of a particular service and the desire of its participants to help colleagues from NIX Solutions and guide them in creating the library. So we got the first list: Safe Browsing API, Drive API, Market Buy, Metrica API.

    So, as we were provided with information from Yandex teams, the modules were sawed, not without bugs, but the work went on.

    To date, the library has grown and includes several modules:
    • OAuth Authorization Module
    • Module for pinger service Search for a site
    • Module for Safe Browsing API
    • Module for Yandex.Disk API (WebDAV)
    • Module for “Shopping on the Market” as part of the Affiliate Market API

    I’ll say just a few phrases about each module, without technical details. We posted all the details on GitHub .

    OAuth Authorization Module
    One of the first modules developed was authorization on Yandex API services. Currently, Yandex services mainly use OAuth authorization, which greatly facilitates the work with them, and working with our library is even easier. Documentation .

    Module for pinger service Search for a site
    If you use the Search service for a site on your site, then you should pay attention to the pinger library, whose task is to inform Yandex about new and changed documents on the site. Documentation .

    Module for Safe Browsing API
    This package is responsible for checking the URL for involvement in untrustworthy sites, so that no infection will catch you for an hour. This service is useful for sites that host links to other resources on the network. Documentation .

    Module for Yandex.Disk API (WebDAV)
    Yandex.Disk confidently scores points as an alternative to various drives, and, I hope, this library will serve as another step in conquering the market. Documentation .

    Module for “Shopping on the Market” as part of the Affiliate Market API
    If your store places offers on Yandex.Market, then you should pay attention to the appropriate library. Documentation .

    Now we are developing a module for working with the Metrica API.

    Development infrastructure

    We not only make the library, but also acquire the amenities for development and testing. GitHub has long been a default platform for many. He managed to grow nice buns that can be screwed to the project in a couple of clicks or in a couple of lines, and I wanted to dwell on them a little more in detail.

    Travis ci

    To connect the Travis continuous integration service, you will need to create a configuration file (you can take ours as a basis ) and connect your project to GitHub at .

    At the moment, Travis is responsible for running unit tests and PSR standards on various versions of PHP (including even HHVM and PHP version 5.6), as well as creating a phar archive with a further upgrade to Yandex.Disk using our library :)

    More Travis CI was already told on Habr -

    The result of integration is available here

    Scrutinizer ci

    Another tool for monitoring the quality of the code allows you to identify potential problems and gives recommendations for improvement (you can use a direct patch, it remains to be copied and applied). The bulk of the work rests with PHP_Analyzer, but not one.

    Project Integration Result -


    This is a simple tool that saves test coverage information for your project. For those familiar with phpunit , this is a clover.xml visualization with tracking changes. Travis is responsible for the data upload; to work, you need to install the “satooshi / php-coveralls” package and the configuration file, for example,

    Result: r / nixsolutions / yandex-php-library

    And a few more “icons” for the collection can be obtained at .

    Instead of a conclusion

    ... And to avoid in the comments the pictures with a trolley from a loaf of bread.

    Profit for NIX Solutions is a PR of our cooperation with Yandex (actually this is the third mention of the company name in this article :). In addition, we have acquired a rather well-known known base for APIs and can help PHP developers answer frequently asked questions on the integration of Yandex services.

    Profit for Yandex - development of a library for a huge PHP community by PHP developers. Partly shifting support to our shoulders.

    Profit for the community - now we have an up-to-date library for working with Yandex services, and each developer can participate in the development of it.

    So, dear Habr, do not be shy and send your questions, but rather pull-requests to GitHub .

    We are waiting, kissing, love.

    Also popular now: