I am having trouble in using documentation. Lets say I want to see the source of function
DB::transaction();
I go to http://laravel.com/api/index.html
and enter in the search form 'transaction'
Nothing is found.
I then try to go on the left to Namespaces/Database which makes sense.
And later I have no idea where to go. There is some namespaces, some classes, some interfaces. Later found out that this is in the connection class, which at first I did not even look at. Connection associates to connecting to the database, not making transaction.
And there often happens when I don't know how to quickly find things.
How do you deal with that?
I assume the documentation should be one of best developers friends, but I guess I found this function by using sublime massive search in all files.
Btw also - I lowed the Codeigniter documentation, so thats why also I am disapointed. In codeigniter everythign looked so simple and search worked very well. Typing same word 'transaction' finds like charm.
Ok, tried same way as CI does to serch:
transaction site:http://laravel.com/api/
then it finds. If there is no other way, maybe I should bookmark the search link and just change the keyword or something like that.
CodeIgniter was definitely simpler, to the point that any larger project suffered greatly under the weight of (forcibly) badly misplaced code. Laravel raises the bar there a little bit, but it's to your benefit as a developer (I promise :D ).
Firstly, kudos for searching through the code. Many people do not. You learn a LOT by looking in there.
Laravel Code
For Laravel, you'll do best by knowing about Namespaces, and how they relate to autoloading files (Namespaces will relate to directories, essentially). You likely know this, but it relates to how you can find classes and their methods.
Now, this doesn't go towards knowing where anything is - that comes with some digging into the code yourself. I almost always have Github open to the laravel/framework repository to look at code.
Note: That API search looks for files, rather than methods within them (unfortunately).
Github
As mentioned, I use Github mercilessly for searching code, instead of the API documentation. The search in Github is quite good - it will search within the current repository.
For example, I searched "function transaction" in github and got good results.
It led me to see here that it accepts a closure, and surrounds the code run within the closure around a transaction. You can see that throwing any exception within that closure will get caught and cancel the transaction (and gives you a way to control it).
Facades
As #matit pointed out, Facades do in fact hide where code is. That's a tricky part. In general, you can call the getFacadeRoot() method on any facade to figure out what class it is:
// Figure out what underlying class the Auth facade actually is
echo get_class( Auth::getFacadeRoot() );
Eventually you'll discover patterns in the code. Most facades point towards certain types of classes within each package (For instance, a Manager class who's job it is to decide which underlying implementation is used).
I really suggest reading Taylor's book which goes into the general architecture of Laravel. It's a quick read which is highly worth it.
Where CodeIgniter excelled in simplicity, Laravel excels in teaching you better coding concepts. Give it some time :D (Or use CodeIgniter still, that's cool too - whatever gets your work done!)
This is why I strongly suggest using CTAGS! I use sublime text 2 with the CTAGS plugin. I just press CTRL+SHIFT+Click on the class method and it will bring up a list of classes that have that method, or if only one exists, take me directly to the file and method. It beats searching the API/docs in terms of speed. There is even a Sublime text 2 plugin for Laravel Facades !
https://github.com/stidges/Laravel-Facades-for-ST
Related
This may be a little subjective, but I feel that best-practice must exist (or even good design when it comes to Laravel apps). Googling results in lots of things that are not to do with the actual points in this question.
Say I am building a web application that has teams, which may have projects, which may have documents.
Should I design the routing so that documents are within the path of the projects they belong to, which are then within the path of the teams they belong to, or keep things at a top level?
As far as I can tell, there are two ends to this spectrum that are worth discussing (other options are just the grey in-between):
Nesting
Example, Doc C is found at: /teams/team-a/projects/project-b/documents/doc-c
It is easy to do this, and in the routing file, I can use route groups to help keep the structure clean. I think it's more logical and perhaps more convenient for the user (they can work out URLs for themselves!). My concerns are that I am importing complexity into each page request:
in checking that the route has integrity (i.e., that doc-c does belong to project-b), and
that the user has authority to access each of the nested assets all the way through the route.
Should I be putting gates/policy checks for every resource at the beginning of each controller method, for every route parameter? Otherwise, where can this be abstracted?
And regarding route integrity, I've never seen examples testing for this - so is this not a common approach? If we don't verify route integrity, then a page could show mixed information by hacking the route (e.g.,/teams/team-a/projects/project-Z/documents/doc-c, would show info about project Z on doc-c's page).
Without Nesting
Example, Doc C is found at : /documents/doc-c
In this example, every asset would have its own base route, more like an API I guess.
No integrity checks required, and the controller would pre-determine the other assets shown to generate the view.
But is this UX good enough? The majority of websites I've seen do not do this.
This is an interesting question - as you mentioned, it may be a little subjective, but worth the discussion.
You touch on a few points, so I will attempt to address them separately.
Nesting vs Not nesting
First thing to clear up in my opinion is browser routes versus API routes. If you are providing an API - either internally to your app or externally to the public, I would avoid nested routes for a few reasons:
resource/id format is quite standard and expressive for API's
this makes it easier to document
this makes it easier for the consumer app to dynamically construct API requests
However, your question does seem to focus on the browser routes. In my opinion browser routes can and should be whatever reads nicely - the url, especially these days, can be considered as part of the UI. For example, you may go to settings (and I would expect to see /settings), from the settings page, if I were to go into the notifications settings section, I would expect to see /settings/notifications.
The routes act and assist with UX - they are almost a breadcrumb and should look as such.
So, I would definitely nest for browser routes, and would definitely not for APIs.
Route integrity
The real heart of your question I think is about the route integrity. I think regardless if you choose to nest or not you need to be checking your permissions with the assumption that someone is tampering with the urls - the same way you assume that the user has tampered with the form input.
Essentially your routes (nested or not) act as input, and you will need to validate that. Route level middleware is one approach, but is often too generic to solve anything complex so you may find it easier to tackle it with controller middleware (https://laravel.com/docs/5.7/controllers#controller-middleware).
So you may do something like:
public function __construct()
{
$this->middleware('auth');
$this->middleware('canViewProject')->only('show');
$this->middleware('canEditProject')->except('store');
}
Whether you use Gates, Policies or just plain old middleware will probably depend on the complexity of the project - but the above applies regardless - treat the urls as input and validate accordingly
I've spent the last year looking at this and refining it, and stumbled upon an elegant solution recently. Nesting can be done nicely, I'm sticking to resource controllers and dot-syntax for nested route resources.
In order to enforce the route validation, I am using something like the following. There is a good answer here, which suggests explicitly binding the models in question.
So with
Route::resource('posts.comments', 'CommentsController');
You'd use
Route::bind('comment', function ($comment, $route) {
return Comment::where('post_id', $route->parameter('post'))->findOrFail($comment);
});
This will automatically work everywhere. If required, you could test for the upstream parameter to be found, and only perform the test in those cases (e.g. to cater for routes where only a comment is specified).
So much work has been subsequently done on Laravel. My default response to this is "yes, use route nesting". I keep routes restful, using (nested) resource controllers wherever possible, and single-action controllers for the odd use case. Route scoping is even automatic now, if specified correctly.
This always has been a discussion between developers even the creators of Laravel have this argument, so what is the good practice?
Lately I've seen a tweet from Taylor Otwell saying that he has deprecated the
nested routes section from Laravel docs because he didn't prefer it, while when you open Laracasts you see Jeffrey is implementing this concept like /series/php-testing/episodes/hello-world.
As I told it's a quiet argument and when it comes to choices like that I always do what it feels good for me. So if I were you I wouldn't nest neither teams or projects but maybe I would nest projects/documents, I don't go for nesting always.
This might be a bit of a deviation from the original question, but I feel that Adam Wathan's Laracon US 2017 talk might be a useful resource for this discussion. (https://www.youtube.com/watch?v=MF0jFKvS4SI)
I am relatively new to development and therefore explore a lot of code bases on github. I always struggle to understand nested routes. So as a best practice I would prefer no-nesting to nesting.
Keeping stuff "CRUDY by design" as Adam calls it, one thing you achieve, imo, is simplification of route names. If I were to work in a group, that is a pattern I would prefer.
However, referring to the penultimate paragraph on your question, I struggle to understand why an integrity check is not needed.
I think you should makes use of Role concepts, Route grouping , Middleware concepts to build this app
For Role related things check https://github.com/spatie/laravel-permission , a good package
Eg:
Route::group(['middleware' => ['role:super-admin']], function () {
//
});
You can almost do any role, permission related things using above package.
Assume roles like project manager, developer.
Group your Routes based on roles & assign proper Middleware as you need.
For URL : /teams/team-a/projects/project-b/documents/doc-c
Check the Authenticated user has a role in team-a & project-b (You can check this in Middleware, Controller or custom Service provider anywhere as your need).
Also just check https://laravelvoyager.com/
Thanks
I've been learning Go for a class course and I am very excited with the language, it really is very useful for web services.
So, I've been writing this CRUD restful API for a final project and I keep running in the damn circular dependency problem. I've already researched and read on the ways of solving it and will post here just for the sake of it, but first the problem I am having:
routes need to know about the handler functions in the handlers package, which in turn need to know about the user structure inside the model package, which in order to send a registration e-mail with a link need to know about the routes path
Classical A -> B -> C -> A
Now, I am trying to write this API using MVC and three layer architecture, this I would love for my routes to be in a controller package, my handlers to be on a business logic package and my user on a model package. This is also needed because I have over 43 model classes, I need them tidy up and tucked away on their package.
Ok, the solutions I found out
1 - Throw everybody on the same package : That's what I've been doing so far but is a very horrible solution for obvious reasons.
2- Pass whatever user needs as argument when it's functions are called: That would be a good solution, but won't work because the function that is being called from user is from an interface implementation because it has to be a generic call and before anyone goes around saying that my problem is because I am forcing generics in go, well too bad, I need that generic, I will not write over 160 crud functions. The whole point of functions is to avoid code repetition.
3- Create another package, with another interface, and have it having a instance of handlers and user and have it pass arguments from one to the other: Despite the reason mentioned above, the need of generic, this sounds like an unnecessarily complicated solution, I refuse to believe that this is better design than circular dependencies.
Bottom line question: How to solve this dependency when C needs to know information from A and generics must be respected
I can post some code here if you need to but I don't see the relevance of specific code when this is more of a high level question.
EDIT: Solved my dependency problem. Thank you all for the comments and answer as it led me to the answer. I don't think I've implemented any of the solutions suggested but it did taught me a lot about how to solve the problem, and they would all be very acceptable and doable solution if it wasn't for my own constrains where I don't want to pass anything to User.
To anyone trying to solve their own dependency problem, what I was able to gather is, instead of making in my case, C ask something from A, give to C whatever it needs, before it has to ask, meaning pass the information to him.
Alas, that was not my solution, what I did was remove the information from A and give the information to Z, now both A and C are asking the path information to Z, which is just a Map, sitting there being all map like and holding information.
Thank you all
You've got some options, and you've found some of them. The main ways of handling this are:
Refactor your design to turn the cycle into a tree. This doesn't really apply to your situation due to your requirements.
Refactor your design to use some kind of dependency injection (this is your 2nd option in your question). This is perfectly viable, and probably the cleanest and easiest.
Refactor your design to take a locally declared interface. This is a more Go-idiomatic version of your option 3. Because interfaces in Go are duck-typed, you get to define it where it's consumed, rather than where it's implemented. So your user package can define a one-method interface for "a thing that gives me a URL I need" and it never needs to reference the package that implements the interface.
This question could apply to all languages and frameworks but I'm looking for something a bit more 'cocoa specific'. I come from a Java background and I've noticed that learning objective-c is a lot more than just syntax, it's almost a completely different way of thinking.
What I've been having the most trouble with, must be the way one has to organise your classes. Sure all basic OOP(Object Oriented Programming) rules apply, and using MVC patterns where you can is recommended. But with me being used to Java I just need to set a few things straight and make sure I've got the right idea:
So for the sake of simplicity let just focus on one part of an app - Logging a user in. You'd have your .xib file for the UI (called Login.xib), you'd have your class that handles your data (connecting to a web service, called LoginModel.m) and you'd have your controller that acts as the middle man between your front-end and data (Called LoginController.m).
Is this is a pretty good example of applying MVC to a Cocoa app? And if it is, does that mean that you'd have 6 files created for this (since you have header files and implementation files). 6 files just to handle something simple as logging a user in. You can imagine how many you'd end up with for an entire app, even the most simplest of ones...
So my question is - Am I doing something wrong? Do I have the wrong idea? Or is the idea of too many files and too long method names just something I need to get used to since my brain is still working in 'Java Mode'?
Your ideas on how to handle that outlined above are fully correct. There is nothing bad about having a lot of files in the project. It does help a lot when you want to reuse code or if for example login details change and you don't want to edit multiple code locations.
Nevertheless, you may combine in such simple cases model class and controller class, especially if your model data can for example be stored in an NSDictionary and such. Only if you have complex model objects, that will run a lot of their own code, it will be better to separate them out.
Variable and method names can't be too long ;) always use a good name that especially describes the functionality or task. You usually don't have to type them often, but Xcode autocomplete will deal with that easily.
I'm reading Taylor Otwell's book in which he suggests using the repository pattern. I get the theory behind it. That it's easy to switch implementations and decouples your code. I get the code too. And it is very nice to be able to switch by App::bind() with some other implementation. But I've been thinking for the last two hours how I should approach things for a new CRM I'm building. Almost no code yet but it might end up big.
I would prefer to simply use eloquent models and collection injected through the controller. That should make everything testable if I'm not mistaken.. . Allowing for mocks and such.
Does the repository pattern maybe offer any benefits towards scalability? In cases when more servers or resources are needed..
And why would anybody want to replace the Eloquent ORM once committed to its use? I mean most projects need a relational database. If I would build a UserRepositoryInterface and an implementation DbUserReponsitory, I cannot see when I would ever need or want to switch that with something else. This would count for most entities in my project (order, company, product, ...). Maybe to use another ORM to replace Eloquent? But I don't see myself doing this for this project.
Or am I missing something? My main concern is to have code that is readable and easy to test. Haven't really been testing that well up to now :)
It does not necessarily mean that ignoring the Repository pattern will give you headaches on the long run, but it certainly makes re-factoring code much easier thus you can easily write Test repositories and bind them with your controllers to easily test your business logic.
So even if it is not likely that you will replace Eloquent or any other part, encapsulating chunks of logic and operations in repositories will still be beneficial for you.
Dependency injection is nothing new in terms of design patterns, will it hurt your code, not necessarily. Will it hurt your ability to easily write / re-factor old code and swap it in easily... absolutely it will.
Design patterns exist as solutions to common problems. I would tell you straight away that ignoring the IoC container in Laravel and not dependency injecting will have a big impact on you later down the line if you're writing complex applications. Take for example that you may want different bindings based on request type, user role / group, or any other combination of factors, by swapping out the classes without impacting your calling code will be beyond invaluable to you.
My advice, do not ignore the IoC container at all.
As a sidenote, Service Providers are also your friend, I'd suggest you get well acquainted with them if you want to write great apps in Laravel 4.
I'm quite new to Prism. I'm studying QuickStarts shipped with it as well as other examples on the net. Almost all of them make modules aware of what region their view(s) get dropped into. Typically, the method Initalize of a module has a line like the the following.
RegionManager.Regions["LeftRegion"].Add(fundView);
I feel quite uncomfortable with that. There's a similar discussion but I think that it should be the responsibility of the shell component to define such mapping. However, I cannot find any example of such approach and I'm not sure whether the bootstrapper is the right place to put such mapping in.
Is this approach completely wrong?
Nothing is completely wrong. But it makes no sense to have the shell/bootstrapper (that by design doesn't know anything about the application it will host) knows what view goes into which region.
Consider an application that can be extended by simply adding modules into a given folder. When you follow the approach that the module knows where it's views want to reside (the mapping is done in Initialize()), this is no problem. I designed my first Prism application that way.
But if your mapping is done in your shell you always have to update your shell (which is part of the base application, not any module) when you want to add another module. This runs contrary to the loosely coupling paradigm. Besides that you have to create one base application for every module constellation. And there are (2^number of modules) permutations you have to cover. That results in loosing your flexibility you gained by using Prism.