I'm using Laravel to create a versioned JSON API that I'll then access with AngularJS to populate my pages. Currently I'm returning the JSON using versioned controllers (eventually I plan to implement dependency injection & versioned repositories instead).
I've attempting to namespace my controllers in the format App\Controllers\API\v1.0 but when I visit localhost:800/api/1.0/companies in my browser, where the JSON is returned, I am notified that Class App\Controllers\API\v1.0\CompaniesController does not exist
. I'm guessing this is because the . is being interpreted like one of the backslashes? I can make the application function by changing the namespace to App\Controllers\API\v1 or App\Controllers\API\v1\v0 , but the former doesn't allow for proper versioning and the latter seems a bit ... inelegant.
What conventions should I use for my namespaces to adequately version my API? Any advice would be appreciated! :)
APIs should only use major versions externally. Following best practice semantic versioning, major versions change when you introduce backwards-incompatible changes to a project.
If you're just adding features, or modifying existing ones in backwards-compatible ways, then you just do it and your existing consumers are not affected (though, they can then make use of the new changes if they want). Your API can change versions from 1.0.0 to 1.1.0 internally, but the version as exposed to your consumers is still just "v1".
If you're just patching bugs, the same applies. Change from 1.0.1 to 1.0.2 internally, but the API should stay at "v1".
Now, if you rename/remove resources, or do some other drastic changes that will break existing clients, your internal version might go from 1.2.0 to 2.0.0, because breaking backwards compatibility requires a major version change. Because of this, the new major version has to be exposed to your API's consumers as "v2".
So, in keeping with this, both your namespaces and your URLs should reflect only the major version (e.g. "v1"), and you should make sure that you never break backwards-compatibility within a major version.
Related
We have developed 2 WordPress plugins which are using same composer package.
Depending on plugin versions the package included in plugin may be changed, we constantly add new functionality to our package.
The problem is that for example plugin A have version 1.0.0 of package, and plugin B have version 1.0.1, WordPress loads only one package , from plugin which loaded first, so if plugin A loaded first then plugin B will use version 1.0.0 package.
We are including autoload.php on both plugins.
Is it possible to do some configuration in WordPress or from composer side to make every plugin load and work with package included on his vendor folder ?
Is it possible to do some configuration in WordPress or from composer side to make every plugin load and work with package included on his vendor folder ?
In general no. The option about namespace rewriting has already been given by Chris Haas, so if you need to rely on different code behind the same global static names, you have to provide a different name for each version.
Another option is you align both plugins to rely on the same dependency version-stability. The example you give with 1.0.0 and 1.0.1 versions, the API should be compatible and it should not be an issue (if the package follows semantic versioning).
From the context of your question, it seems the dependency has not yet matured enough that this is an option practically.
Instead it should be possible to have the plugin which is currently based on 1.0.0 to use 1.0.1 as well. Then the version conflict is solved, as now it is the same version and can use the same names. This may not be an ideal solution, but could get you back to a working version fast and gives you more room to consider a better way in the future (e.g. having a build for those plugins that use scoping).
Additionally you could/should wrap all access to third-party libraries once in your own code so that such problems aren't that deep reaching (dependency issues tend to be harder to resolve). This methodology is independent to Wordpress or Composer, just a recommendation on how to interface to third-party dependencies (or even Wordpress itself[1], which you may know better).
If however what you ask here is already such a wrapper you build your own (e.g. in form of a composer package), consider to adhere to semantic versioning and stabilize its API first.
PHP has no built-in utility to create archives apart from PHAR, e.g. that you can have imports via names but to different code. This is likely also the reason why Composer does not support it and instead provides PSR-0/PSR-4, classmap and file inclusion autoload configuration.
As you have the scenario to share the same namespaces across the plugins - there is no other option actually as it runs in the same PHP process - the first one wins. You may however make your own plugins interoperable so that they can establish a loading order in their own hierarchy, e.g. to prefix the one autoloader before the other conditionally if it exists.
I'd probably go with scoping in the first place and only share build utilities between the plugins nowadays and have a nice package for each plugin afterwards. Yes, scoping can be PITA, but if you have this early on, you don't have to solve this later which is much harder.
Compare for the level of WordPress plugins WordPress Plugin: How do I avoid "tight coupling"? and Multiple Custom Metabox Help - both well dated so it is easier to not take code verbatim but to develop own conclusions.
I was wondering if it's a good idea to use PHP's namespace / autoloading to version my code. The file system would be something like /Class/<Package>/<version#>/<ClassName>, and a PSR4 autoloader maps new <OurVendorName>\<Package>\<version#>\<ClassName>() to the appropriate directory. We also have a /vendor/ directory for other vendors' packages we use.
My thoughts are to have a bunch of packages that run specific groups of logic, and a Slim router would use only the API package. The API package would essentially be a bunch of controllers pulling up the appropriate versions of the other packages and running them.
Doing so would allow the team to work independently on logic packages and only release new versions when backwards incompatible changes are being made. Other packages could migrate to new versions of their dependencies at their own pace without breaking anything. When we deprecate versions of packages, we can make the base object log the call stack upon instantiation to make refactoring easier to trace. Our API would also be versioned, so specific Slim routes could migrate to different versions of the API at their own pace.
I don't really see many flaws with this approach, but one possibility I considered was that it would be too much overhead. Between the filesystem holding multiple versions of every package and classes instantiating multiple versions of the same class would there be a potential performance hit? Also, would this level of granularity cause more headaches than it's worth? This is a project that is evolving very rapidly, so we need a system where we can quickly update our code without breaking anything.
I made a Symfony2 bundle, which works fine with SensioFrameworkExtraBundle 2.x
But since Symfony 2.4, the SensioFrameworkExtraBundle used is 3.x and the apply() and supports() methods signature have changed.
This forces me to maintain 2 versions of my bundle... only because of that.
Is there a way to easily handle this kind of situation?
Is there some nice workaround I didn't think about?
Because it's very tedious to manage updates and fixes on 2 "identical" versions, living in parallel (modifying master branch, commit, switching to other branch, cherry-picking master commit, push the two versions, creating 2 release each time...)
Well, generally you do make a new version if your dependency API changes - aka on it's new major version.
Anyway, if those two methods are the only thing bothering you, you should write an adapter that will on one side expose fixed standard API towards your classes, while on the other side it will know how to use different/specific API of the dependency API different versions. Then you don't have to maintain two almost identical versions of your code, but only that adapter in single version. That way your code will depend on that adapter rather then the dependency itself, so you can tweak the adapter to accommodate new versions of dependency w/out changing the rest of your code.
In the Symfony 2 docs it's said:
A bundle should not embed third-party libraries written in JavaScript, CSS, or any other language.
Then how should I do that? I want to install Twitter Bootstrap, DataTables, and many other things as dependencies using Composer. But the only way I can think of is creating a bundle and embedding them.
What is the correct way to do this?
You should use Bower by Twitter. It is a package manager for HTML, CSS and Javascript. It was created to address this very issue you are having.
EDIT:
As of now, there are very good package managers for JS Libraries such as Bower, Jam or Component.
Versioning system
Semantic Versioning - Composer advises to use the semantic versioning system. It uses a X.Y.Z setting, in which X is the major version, Y is the minor version and Z is the patch version. Y and Z should always be backwards compatible while X reflects changes in code which MIGHT break backwards compatibility.
Embeding
Embeding should be read as copy and pasting the code (and binary) as part of your library, rather then requiring it as a third party (vendor) package/bundle. Its like including query.js in a resource folder or copying and pasting propel code to a folder inside your bundle.
Why not embed 3rd party libs
A bundle should not embed third-party libraries written in JavaScript, CSS, or any other language.
This statement comes from a best practice point of view. Embeding (as in copy/paste) third party libraries of any kind (PHP libs especially) is usually not a good idea. For instance, imagine that BUNDLE A uses LIBRARY FOO v1.4.1, and BUNDLE B also uses LIBRARY FOO but with a different version v1.5.2. If any of the BUNDLES (A or B) embeds FOO lib, they might (most probably will) become incompatible. For instance, php classes and functions cannot be redeclared. Any of the bundles can, of course, use workarounds to mitigate this problem, such as namespacing their version of FOO or autoloading rules, but this can rise other problems as well besides surely increasing memory usage as there are 2 versions of the same thing parsed by PHP.
If a PHP package does not follow this best practice, the errors that arise are usually easy to spot (with error: cannot redeclcare function blablabla). With Javascript Libraries, however, that is not true. You can redeclare functions (as they are object properties). So if now FOO is a JS Lib instead, and BUNDLE A and B embed them into their libraries, when they are included, strange problems can arise. For instance, a function can be redeclared that lacks a crucial functionality for one of the bundles and break it.
Symfony is a PHP framework.
It deals with PHP libraries/bundles. Symfony advises to require a library as dependency instead of embedding it since it uses Composer as a Package manager, which takes care of downloading and loading the require packages. As far as I remember, when 2 bundles/packages use the same library, if they have different version requirements, the most actual is used, unless its backwards incompatible. Composer then reports a conflict that you have to manually resolve.
However... There is no way to handle javascript libraries properly. That's because Composer is a package for PHP libraries. You can workaround this in two ways I can think of: (there are probably more and best ways to handle this, I just thought of these two, read them as suggestions)
Create a PHP wrapper around the javascript library and including it (although this potentially creates the same problem if another bundle decides to do the same thing but giving the package a different name)
Creating a bundle which requires the javascript library as a third party dependency through composer. Since the javascript library won't probably have a composer.json file in it's repository (sometimes they live as a standalone minified file), this can be accomplished by creating a custom composer installer, forking the javascript repository (in gitHub for instance) adding a composer.json to it, etc... However, you will need to constantly maintain and upgrade the said library, which can be troublesome.
You will have to keep in mind that:
JS and CSS libs have to be exposed publicly, so that the client can access it (security considerations)
Symfony is a PHP framework and deals with server-side packages. JS/CSS are client side. This as to be taken in consideration so it works properly.
One of the main ideas behind symfony (as with other PHP Frameworks) is code reusability within and between projects. Pure Javascript Library are reusable in themselves. They are usually self contained. Besides, there is no real gain in "bundling" a JS library from the server side. You don't need any kind of bundle to achieve reusability.
My Approach
Since the composer system is so appealing, specially when deploying bundles/packages/libraries to other people, my approach to using third party javascript/css libraries was to create a dependency manager specific to JS/CSS that other packages/bundles could rely on to take care of their JS/CSS dependencies without worrying about this.
My sugestion
If you are planing to release your project to the public, namely as a symfony bundle, you should plan carefully how to approach this.
If your project is self contained (personal use or to a client, not widespread use) then this has much less relevancy since you (the programmer) have total control in what third party tools you use and include in your project. These are just best practice "suggestions" to avoid
future problems.
I would like to know about the compatibility between upcoming versions of KO3. I have heard that once 3.1 comes in, it won't be easy to simply upgrade to it from kohana 3.0 (Wordpress upgrade is pretty swift from 2 to version 3)
If I create my project in KO3 (currently using 3.0.6.2), what are the chances that my project will be easily upgradable to 3.1 or above versions without breaking anything ?
Please answer if you are a real pro on KO3 or part of the development team.. This is important.
Major versions (eg: 3.0 to 3.1) may change the API. Currently, the biggest API change will be splitting the Request class into Request and Response, as well as changes to Request that allow external routing. This also implies that the Remote class will be significantly modified to removed completely in favor of external requests and responses.
You can keep track of the changes scheduled for 3.1 by following the 3.1 roadmap.
I'd just like to point out that wordpress is an entirely different system, it's basically an application written on their own framework whereas kohana is just the framework and you supply the application.
If the wordpress core framework changes then they also change their application to account for those modifications. Sometimes plugins aren't compatible across upgrades so the plugin author has to release an update which makes it compatible. All of this is hidden from the front end users, they don't need to be aware of how it works in order to use it.
Kohana on the other hand has no gui or front end, you're getting nitty gritty with the code. If an interface changes then you'll have to adapt your implementation to suit, there's no way around that.
And as antpaw said, unit tests are always useful for making sure things work as expected! For more info see the unittest repo
it highly depends on the features your have used. give it a try and watch your logs or even better: you run unittests. http://github.com/kohana/core/compare/3.1...master if i picked the right repository. this will help you to see the difference betwenn ko3.1 and ko3.0.7