Answers.Body: <blockquote>
    <p>If you want your extension to store data in the database, then you will need to create a new entity.</p>
  </blockquote>
  
  <p>IMHO, this line miscommunicates a little. The value of <code>generate:entity</code> comes when you want to define an entirely new entity with a full CRUD functionality in APIv3. There are times when you'd do this. But if that's not the goal, then there are certainly other ways to store data which may be simpler, e.g.</p>
  
  <ul>
  <li>You can often store data using a core entity (like <code>Activity</code> or <code>Contact</code>), possible with custom fields.</li>
  <li>You might create a bare SQL table and generate the SQL code in your own way.</li>
  </ul>
  
  <p>IMHO, the docs for <code>generate:entity</code> should not negate the value of these other approaches.</p>
  
Answers.ContentLicense: CC BY-SA 3.0
Answers.CreationDate: 2017-05-13T19:10:44.357Z
Answers.LastActivityDate: 2017-05-13T19:10:44.357Z
Answers.UserDisplayName: Tim Otten
Answers.Body: <p>The benefit of going through the pain of DAO and co is not obvious for me neither, and I have to confess skipping them and doing it the same way as you did.</p>
  
  <p>One key reason would be to benefit from all the security that the DAO handles by default: are you sure your extension is done properly and you properly escape all the SQL?</p>
  
  <p>On other reason might be documentation: it might be easier to find which fields exist/are mandatory based on the schema/BAO. Eg. on the API explorer, are all the fields for your extension properly shown and do they have their description?</p>
  
  <p>I know that some work was done to use a more modern SQL abstraction than the one we have, but I don't think it is something that we could use in extensions. Would be super useful IMO.</p>
  
Answers.ContentLicense: CC BY-SA 3.0
Answers.CreationDate: 2017-05-11T10:54:36.847Z
Answers.Text: Thanks, Xavier, yeah, I've just used `$result = CRM_Core_DAO::executeQuery($sql, $queryParams);` a lot with placeholders and typed params. I get it that schema is useful for API documentation, I had a hunch that was something to do with it. But the [dance](https://docs.civicrm.org/dev/en/master/extensions/civix/#generate-entity) you have to do to get there is pretty elaborate!
Answers.UserDisplayName: artfulrobot
Answers.ContentLicense: CC BY-SA 3.0
Answers.CreationDate: 2017-05-11T10:50:27.980Z
Answers.LastActivityDate: 2017-05-11T11:33:00.190Z
Answers.LastEditDate: 2017-05-11T11:33:00.190Z
Answers.UserDisplayName: Xavier
Answers.Body: <p>I'm guessing that if it wasn't so painful (e.g. if there was a CLI command or similar that created the boilerplate and so on) then you would just follow the guidance and not question the reasons.</p>
  
  <p>I have skipped them in the past, esp. for more trivial extensions, but went to the effort recently, on a more complex extension.</p>
  
  <p>Not having to worry as much about security (as Xavier mentioned) is one reason. Allowing exposure to BAO level hooks like <a href="https://docs.civicrm.org/dev/en/master/hooks/hook_civicrm_pre/" rel="nofollow noreferrer">https://docs.civicrm.org/dev/en/master/hooks/hook_civicrm_pre/</a> might be another (though I haven't thought too much about this reason).</p>
  
  <p>Following CiviCRMs conventions is possibly another. Though having said that. I do agree with the sentiment of the question and we should be trying to work out which conventions are useful and which aren't.</p>
  
Answers.ContentLicense: CC BY-SA 3.0
Answers.CreationDate: 2017-05-11T11:43:19.727Z
Answers.Text: Thanks, Michael, can you elaborate about the BAO level hook example?
Answers.UserDisplayName: artfulrobot
Answers.ContentLicense: CC BY-SA 3.0
Answers.CreationDate: 2017-05-11T11:08:21.387Z
Answers.LastActivityDate: 2017-05-12T11:54:12.713Z
Answers.LastEditDate: 2017-05-12T11:54:12.713Z
Answers.UserDisplayName: michaelmcandrew
Answers.Body: <p>Another reason to have full-blown entities that make use of core-like DAOs is that you inherit a bunch of API magic, like the ability to do API joins across tables, the use of get options, etc.</p>
  
Answers.ContentLicense: CC BY-SA 3.0
Answers.CreationDate: 2017-05-16T18:07:00.967Z
Answers.Text: Yeah, I had a hunch it might bring that in. Thanks.
Answers.UserDisplayName: artfulrobot
Answers.ContentLicense: CC BY-SA 3.0
Answers.CreationDate: 2017-05-16T17:24:47.167Z
Answers.LastActivityDate: 2017-05-16T17:24:47.167Z
Answers.UserDisplayName: universalhandle
Body: <p>The Developer Guide includes <a href="https://docs.civicrm.org/dev/en/master/extensions/civix/#generate-entity" rel="noreferrer">detailed instructions on declaring a new entity</a> which begins with this:</p>
  
  <blockquote>
    <p>If you want your extension to store data in the database, then you will need to create a new entity.</p>
  </blockquote>
  
  <p>The steps include:</p>
  
  <ol>
  <li>create XML <a href="https://docs.civicrm.org/dev/en/master/framework/schema-definition/" rel="noreferrer">schema</a></li>
  <li>create <a href="https://docs.civicrm.org/dev/en/master/core/architecture/#dao" rel="noreferrer">DAO</a></li>
  <li>create BAO</li>
  <li>create SQL to create/drop your table</li>
  <li>create Api</li>
  </ol>
  
  <p>I must confess that I have stowed new data in a more lightweight way on several extensions - e.g. I've created an API Entity that handles the SQL itself, skipping the creation of XML, DAO and BAO.</p>
  
  <p><strong>I am sure there are good reasons for the detailed set of steps but it's not clear to me what benefits they bring?</strong></p>
  
  <p>In black-box thinking, an extension that needs to use a new table needs to be able to create the table, provide an Api for using it, delete the table on uninstall. Are there cases, e.g. a table for a very extension-specific use case, when it is sensible to avoid the overhead of all the extra boilerplate code (schema, DAO, BAO)?</p>
  
Tags: <extension><developer>
Title: Why is it important to define new Entities for new types of data?
ThreadText: # Why is it important to define new Entities for new types of data?
  
  (Asked by: username_0 on 2017-05-11)
  
  The Developer Guide includes [detailed instructions on declaring a new entity](https://docs.civicrm.org/dev/en/master/extensions/civix/#generate-entity) which begins with this:
  
  > If you want your extension to store data in the database, then you will need to create a new entity.
  
  The steps include:
  
  1. create XML [schema](https://docs.civicrm.org/dev/en/master/framework/schema-definition/)
  2. create [DAO](https://docs.civicrm.org/dev/en/master/core/architecture/#dao)
  3. create BAO
  4. create SQL to create/drop your table
  5. create Api
  
  I must confess that I have stowed new data in a more lightweight way on several extensions - e.g. I've created an API Entity that handles the SQL itself, skipping the creation of XML, DAO and BAO.
  
  **I am sure there are good reasons for the detailed set of steps but it's not clear to me what benefits they bring?**
  
  In black-box thinking, an extension that needs to use a new table needs to be able to create the table, provide an Api for using it, delete the table on uninstall. Are there cases, e.g. a table for a very extension-specific use case, when it is sensible to avoid the overhead of all the extra boilerplate code (schema, DAO, BAO)?
  
  **Tags:** extension, developer
  
  
  ---
  
  ## 4 answers
  
  ### Answer by username_1 on 2017-05-13. Score: 2 | Accepted answer
  
  > If you want your extension to store data in the database, then you will need to create a new entity.
  
  IMHO, this line miscommunicates a little. The value of `generate:entity` comes when you want to define an entirely new entity with a full CRUD functionality in APIv3. There are times when you'd do this. But if that's not the goal, then there are certainly other ways to store data which may be simpler, e.g.
  
  * You can often store data using a core entity (like `Activity` or `Contact`), possible with custom fields.
  * You might create a bare SQL table and generate the SQL code in your own way.
  
  IMHO, the docs for `generate:entity` should not negate the value of these other approaches.
  
  
  ---
  
  ### Answer by username_2 on 2017-05-11. Score: 3
  
  The benefit of going through the pain of DAO and co is not obvious for me neither, and I have to confess skipping them and doing it the same way as you did.
  
  One key reason would be to benefit from all the security that the DAO handles by default: are you sure your extension is done properly and you properly escape all the SQL?
  
  On other reason might be documentation: it might be easier to find which fields exist/are mandatory based on the schema/BAO. Eg. on the API explorer, are all the fields for your extension properly shown and do they have their description?
  
  I know that some work was done to use a more modern SQL abstraction than the one we have, but I don't think it is something that we could use in extensions. Would be super useful IMO.
  
  > **Comments:**
  > **username_0**: Thanks, username_2, yeah, I've just used `$result = CRM_Core_DAO::executeQuery($sql, $queryParams);` a lot with placeholders and typed params. I get it that schema is useful for API documentation, I had a hunch that was something to do with it. But the [dance](https://docs.civicrm.org/dev/en/master/extensions/civix/#generate-entity) you have to do to get there is pretty elaborate!  
  
  ---
  
  ### Answer by username_3 on 2017-05-11. Score: 2
  
  I'm guessing that if it wasn't so painful (e.g. if there was a CLI command or similar that created the boilerplate and so on) then you would just follow the guidance and not question the reasons.
  
  I have skipped them in the past, esp. for more trivial extensions, but went to the effort recently, on a more complex extension.
  
  Not having to worry as much about security (as username_2 mentioned) is one reason. Allowing exposure to BAO level hooks like <https://docs.civicrm.org/dev/en/master/hooks/hook_civicrm_pre/> might be another (though I haven't thought too much about this reason).
  
  Following CiviCRMs conventions is possibly another. Though having said that. I do agree with the sentiment of the question and we should be trying to work out which conventions are useful and which aren't.
  
  > **Comments:**
  > **username_0**: Thanks, Michael, can you elaborate about the BAO level hook example?  
  
  ---
  
  ### Answer by username_4 on 2017-05-16. Score: 1
  
  Another reason to have full-blown entities that make use of core-like DAOs is that you inherit a bunch of API magic, like the ability to do API joins across tables, the use of get options, etc.
  
  > **Comments:**
  > **username_0**: Yeah, I had a hunch it might bring that in. Thanks.  
  
  ---
  
  