Repository navigation
Criteria again? #60
Replies: 13 comments 13 replies
|
Lol, I agree! Very happy to hear someone feels as passionate about this as I do! I loath those goddamn Criteria classes. They are mostly undocumented, probably stopped being maintainable in the early days of the project, they do everything, just not in the way you want them to, the name does not make sense (quite a lot of the names do not make sense), they expose tons of internal methods into userspace further plumping up the already bloated interface, and they are just everywhere in Propel. The name "Criteria" I think was taken from the active record pattern, and while I commend the academic aspirations, calling it "Query" would have significantly helped literally everybody who worked with Propel. From what I gathered, I suspect the Criteria/Criterion classes were there first, and the rest of Propel was built around it. I think they were developed as a pocket-knife for data base interaction, an object from a library not unlike Lots of it only started making sense when taking it apart. What you (rightly) mock about in that code - adding filters on different tables in one Criteria, adding values in another, Propel then figuring out the tables and running updates on all of them in a completely opaque way - presumably all goes back to that initial pocket-knive approach, and seeing how this was used internally (I think you can still do this with generated Propel2 query classes, i.e Note however that I removed this functionality. The code you cite is an example of what you cannot do in Perpl anymore. If you were playing Russian roulette with you data before, you'll have to change that as it throws an exception (here). If it hasn't become clear, I would burn it with fire, but in light of projects still around which had to use it, I guess some BC is a better way to go. But I understand the confusion. I wanted to be as transparent and verbose as possible in the README, yet it's probably irritating at best and discouraging at worst. Do you think I should remove those parts from the doc? Sorry for the long text! But it was admittedly fun to type it out. Several two cents piled up over the years about those darn Criteria classes... Are you still using Criteria directly in your project, or did you put bleach to it? |
|
IIRC, Propel 1.4 added the fluent Query classes. Prior to that, everything was Criteria. They did that after Doctrine's query builder. And IMO, did a better job than Doctrine. But alas, it was Datamapper vs ActiveRecord and Symfony had already thrown their weight behind DataMapper. History was written. We refactored a ridiculous amount of code from Criteria to Query logic at the time. |
|
@mringler I appreciate the explanation. Your 'readme' contains this documentation:
Following that you should preface each example with: "If you are writing this type of query..." and then direct them to another page explaining what they need to do to update their code. The exceptions you have listed may be valid, but they are scary to anybody that is scanning the page. Cheers |
Perfect, yes, I'll updated this soon.
Interesting. The way ModelCriteria code is written around Criteria - with determination but limited sensibility - gave me the impression they did not come from the same project. |
@oojacoboo and somewhere in-between you had ModelPeer classes too. Those got renamed to ModelQuery if I remember well? |
|
Yeah, Criteria/ModelCriteria etc. ... I have banged my head on the desk already a couple of times for this. I have not even mastered them because you get stuck at simple things like Boolean logic. Simple things like EQUAL/NOT_EQUAL or IN/NOT_IN or LIKE/NOT_LIKE sometimes work and sometimes they don't. Like for no apparent reason. It's like you throw dice. It will work or not - but you don't know why. If I could just find out if I am too stupid to work things out or not - that would be fine. But it does not work like that because sometimes it works just like expected and sometimes not. It is just frustrating. And sometimes, I needed to go as far as fiddling with the whole hidden iceberg like TableMap, Peer, ColumnMap and whatnot. My personal believe is - I as a simple user should not be dealing with such things. But welcome to reality. In my quest of understanding the inner workings of Propel to understand what I am doing wrong, I have spent countless hours of "googling" and looking for hints on Stack Overflow (spoiler alert: although very painful, googling is more effective then SO because noone seems to care about Propel on SO since ten years). And it took me a fair amount of time to even realize how to get at least some information of what I needed. At https://api.propelorm.org/. Because this site is not even properly "googleable". SEO anyone? You have exactly to know what you are looking for to even get to this site. OK, I could have bookmarked it. I was admittedly naiive. But it brings me to the point, which is important from my point of view: this whole site, https://api.propelorm.org/ seems to have been spat out over ten years ago via an automated tool. At least that is what the readme.md says on https://github.com/propelorm/api.propelorm.org. So, besides the fact that this documentation is oftentimes not informative enough, the question is of course how accurate this can be after more then 10 years. I would like to suggest the following for https://github.com/mringler/perpl:
And as a future, wishful thinking goal - rewrite this whole iceberg that has a long history of good intentions. As the road to hell is paved with good intentions. As a good thing, we cannot do anything wrong - as the current policy for the main repo seems to be as conservative as possible. We can - and surely are about to - make mistakes but we will have tried to evolve. As @smhg said - Let's try to get things moving? |
Oh yea, totally forgot about the Peer classes... |
|
@kasparsatke I agree on the docs. I think this needs forking probably and implemented as part of this repo. I think the branding for It seems like the same discussions on the future of Perpl/Propel keep popping up across various issues/discussions. It'd be good to keep issues on topic and have these conversations in a single or multiple discussion threads. |
|
@kasparsatke I smiled reading your text. Do I know about it. Seems like Propel is trying to make things easy for you by not having you type out all the information you have, to then guess what you actually meant from the limited information it has, often getting it wrong. At which point you are screwed. I find the manual at https://propelorm.org/documentation/ pretty helpful (didn't even know about the API doc), but considering how convoluted it is, and how idiosyncratic names and functionality in Propel often are, looking at the code is often unavoidable. Updating the docs would be great, but I don't think I'll have the time to do that. But maybe someone else does? It'd be great to make it easy for people to participate. Any ideas how to do that? Are there roles/permissions I can throw at you that would allow you to do something here that you want to engage in? |
|
@mringler I would cautiously say I could do a little from time to time bit I’d rather underpromise. I am pretty lousy at OOP because I am with my mind still stuck in in a time when that wasn’t a „thing“ and also find it less opaque and errorprone without too much OOP. I know, my mindset is certainly not ideal for coding an ORM :-) Although there are definitely things that annoy me so much that I would like to improve them. On the other hand I can write long and convoluted documentations ;-) On the top of my mind - the question pops up: have you already done some documentation for all the fixes and new features that are within Perpl? |
|
Since this topic is now mainly about documentation: The Propel 1.x docs where meant to be deprecated as soon as the 2.0.0 release happened. Since it didn't, I've been grateful someone kept them online. I've only migrated from 1.7.2 to 2.0.0-beta3 in June 2023. The API docs where never that useful to me. An IDE with LSP support gives you better help, no? I remember I had the feeling maintaining the docs was one part why Will Durand never got to release (his) 2.0.0. It takes a lot of effort for most people. Maybe now feedback on issues and PRs are less of an issue as they were back then though? |
|
Well, @kasparsatke , writing documentation is criminally underrated in Propel, as we all seem to agree on. So if this is something you are accustomed to do, I'm sure you could do some good with that, both for Propel and Perpl users.
I typically write short documentation in the PRs and combine those in the readme. But ideally, those changes should be integrated into a structured documentation, i.e. I have contributed a bit to the 2.0 docs, the process and ultimately the result I found a bit lackluster. It's basically a bunch of markdown files that are turned into html, and you end up with too long pages with confusing navigation, a layout that you have almost no control over (and don't know how your edits will look when published), and since editing is done through PRs, it really does not cater to small improvements, but rather large chunks being written once and then they are what they are. A managed wiki would probably make things much, much easier. Turning those markdown files into wiki pages shouldn't take too long. @smhg, this might be something you could start in Propel2? Of course I'd be happy to have it here too. Maybe I'll look at that in the next days, seems like something you can setup while half-watching tv. But if that's something you feel passionate about, @kasparsatke , I am happy to do the setup and leave it to you :) |
|
Hey @kasparsatke, great ideas! I have created a new repository for perpl and added a repo for the page at perplorm/perplorm.github.io. This makes the documentation available at https://perplorm.github.io. To make it different from the Propel docs, I did some quick edits to the header, but otherwise, it is the same as before. Yes, isn't it great that the disfigurement of "Propel" gives something that sounds like "purple" (and also "people")? I like that. But I am also not sure if the color works. I'm happy to use a different one. After all, what's in a name? You should should have gotten an email that you are an admin of the repo. Is that something you are interested in? If you like, edit away! This repo is probably going to move to perplorm as well. |


Uh oh!
There was an error while loading. Please reload this page.
I started using Propel 1.4 (I think) - it was around 2007 and have been coding with it now for 18 years. Back then we did a lot with the 'Criteria' class, and it has been good to see it disappear over the years. It was a cludge then and it looks like you are re-implementing a new cludge. I looked through your notes (for Propel users upgrading) and there really didn't seem to be a clear use case for Criteria, it just seems to popup to do some hairy things. Like this:
I'm not really sure why you would ever write something like this. I had to read that code about four times before I understood what you were trying to do.
Why would anybody ever write this code? It's not readable, it's certainly not clear what is supposed to happen (because of the separation between the condition and the update).
The only time I want to type Criteria is when I need Criteria::NULL
All reactions