Establish entity interface and database service for login tokens.

[demiankatz]

No description provided.

[demiankatz]

Since this method has never been included in released code, I decided it was safe to delete it now that the logic has been refactored to the LoginTokenService, rather than going to the trouble of retaining a deprecated version.

[aleksip]

Looks otherwise good to me, however the signature of DbServiceInterface::saveToken() seems a bit odd. I would expect a saveToken() method to accept a LoginTokenEntityInterface, instead of creating one.

I think I would rather have a simple saveToken(LoginTokenEntityInterface $token) and have the caller create and populate the token. Or offer both possibilities with an additional createAndSaveToken() with the current saveToken() parameters.

[demiankatz]

@aleksip, I don't think there's a need for a saveToken method that only saves the token, since the existing persistEntity method will do exactly the same thing. Thus, I've just taken your suggestion and renamed the method to createAndSaveToken for clarity. What do you think?

I also notice that there's a fairly similar saveToken method in the OaiResumptionService. Should I open a separate PR to rename that one to match?

[aleksip]

@demiankatz Oops, I missed persistEntity() completely, looking at only LoginTokenServiceInterface. I wonder if we should move createEntity() to DbServiceInterface as well? Or are there cases where we allow persisting entities but not creating them?

This of course changes things slightly, although createAndSaveToken() is still more informative. But now I'm wondering if it should be createAndPersistToken() to better fall in line with the basic methods... 😅 Naming things is hard, and I don't have a strong opinion here. Whatever the decision, it would seem good for the method in OaiResumptionService to be similarly named.

[demiankatz]

@aleksip, the difference between createEntity and persistEntity is that persistEntity will persist ANY type of entity, but each service has its own distinct createEntity method that creates a specific type of entity for that service. While we could put createEntity in the top-level DbServiceInterface, this would require us to give it a very broad return type, which might be less informative than defining it in narrower terms in each individual service. There might also be an argument for changing persistEntity to be more narrowly typed, with a different implementation in each service. That would be advantageous if we needed to implement special handling for specific types of entities, but it would also add a lot of boilerplate code, so I'm not sure if the advantages outweight the costs.

In any case, I like your idea about renaming the method to say "Persist" instead of Save." I'll take care of that in a moment.

[aleksip]

the difference between createEntity and persistEntity is that persistEntity will persist ANY type of entity, but each service has its own distinct createEntity method that creates a specific type of entity for that service

@demiankatz Ah, yes of course. But is it really possible and/or good that e.g. a call like LoginTokenServiceInterface::persistEntity(UserEntityInterface $entity) can be made?

[demiankatz]

@demiankatz Ah, yes of course. But is it really possible and/or good that e.g. a call like LoginTokenServiceInterface::persistEntity(UserEntityInterface $entity) can be made?

I think it depends on the level of granularity of the services we create. If we want to strictly say that each service class can only deal with one type of entity, then it would make sense to be more restrictive. However, there are some edge cases where flexibility may be justified -- especially situations where linking tables are involved. For example, if we want to add a new resource to a favorite list, do we want to require access to the ResourceService and the UserResourceService to accomplish this, or might it be better to allow the ResourceService or the UserService to do all of the work? I'm inclined to think requiring separate service access for linking tables may be overcomplicated, and that's the main reason I've left persistEntity open-ended for now. There's certainly an intermediate approach where ResourceService::persistEntity could accept ResourceEntityInterface|UserResourceEntityInterface, etc.... but I think if we try to get too specific before the design is more mature, we may paint ourselves into corners. As we get deeper into the refactoring, we may still find ourselves wanting to move things around, and I want to make that as easy as possible for now. Thus, it feels to me like it may be best to leave this open-ended until it's a bit more mature, and then consider tightening it up.

[aleksip]

@demiankatz Makes sense, especially the not painting ourselves into corners part. Maybe one option would be to have separate higher level services for the cases where linked tables are needed? Anyway, this PR LGTM!

[demiankatz]

@demiankatz Makes sense, especially the not painting ourselves into corners part. Maybe one option would be to have separate higher level services for the cases where linked tables are needed? Anyway, this PR LGTM!

Yes, it's definitely possible that we'll need some separate higher-level services to reorganize things after the first round of refactoring is done. I'm keeping an open mind about that -- just a question of how to namespace/organize things if we do find that we have that need.