README
1NAME
2 DBIx::Class::BitField - Store multiple boolean fields in one integer
3 field
4
5VERSION
6 version 0.13
7
8SYNOPSIS
9 package MySchema::Item;
10
11 use base 'DBIx::Class';
12
13 __PACKAGE__->load_components(qw(BitField Core));
14
15 __PACKAGE__->table('item');
16
17 __PACKAGE__->add_columns(
18 id => { data_type => 'integer' },
19 status => { data_type => 'integer',
20 bitfield => [qw(active inactive foo bar)],
21 },
22 advanced_status => { data_type => 'integer',
23 bitfield => [qw(1 2 3 4)],
24 bitfield_prefix => 'status_',
25 accessor => '_foobar',
26 is_nullable => 1,
27 },
28
29 );
30
31 __PACKAGE__->set_primary_key('id');
32
33 __PACKAGE__->resultset_class('DBIx::Class::ResultSet::BitField');
34
35 1;
36
37 Somewhere in your code:
38
39 my $rs = $schema->resultset('Item');
40 my $item = $rs->create({
41 status => [qw(active foo)],
42 advanced_status => [qw(status_1 status_3)],
43 });
44
45 $item2 = $rs->create({
46 active => 1,
47 foo => 1,
48 status_1 => 1,
49 status_3 => 1,
50 });
51
52 # $item->active == 1
53 # $item->foo == 1
54 # $item->status == ['active', 'foo']
55 # $item->_status == 5
56 # $item->status_1 == 1
57 # $item->status_3 == 1
58
59 $item->foo(0);
60 $item->update;
61
62DESCRIPTION
63 This module is useful if you manage data which has a lot of on/off
64 attributes like *active, inactive, deleted, important, etc.*. If you do
65 not want to add an extra column for each of those attributes you can
66 easily specify them in one "integer" column.
67
68 A bit field is a way to store multiple bit values on one integer field.
69
70 The main benefit from this module is that you can add additional
71 attributes to your result class whithout the need to deploy or change
72 the schema on the data base.
73
74 This module encourages to not normalize your schema. You should consider
75 a "has_many" relationship to a table which holds all the flags instead
76 of this module.
77
78 Example
79 A bit field "status" with "data_type" set to "int" or "integer" (case
80 insensitive) and "active, inactive, deleted" will create the following
81 accessors:
82
83 "$row->status"
84 This is not the value which is stored in the database. This accessor
85 returns the status as an array ref. The array ref is empty if no
86 status is applied.
87
88 You can use this method to set the value as well:
89
90 $row->status(['active', 'inactive']);
91 # $row->status == ['active', 'inactive']
92
93 "$row->active", "$row->inactive", "$row->deleted"
94 These accessors return either 1 or 0. If you add a parameter they
95 will act like normal column accessors by returning that value.
96
97 my $foo = $row->active(1);
98 # $foo == 1
99 # $row->active == 1
100 # $row->status == ['active']
101
102 "$row->_status"
103 This accessor will hold the internal integer representation of the
104 bit field.
105
106 $row->status(['active', 'inactive']);
107 # $row->_status == 3
108
109 You can change the name of the accessor via the "accessor"
110 attribute:
111
112 __PACKAGE__->add_columns(
113 status => { data_type => 'integer',
114 bitfield => [qw(active inactive deleted)],
115 accessor => '_status_accessor',
116 },
117 );
118
119 ResultSet operations
120 In order to use result set operations like "search" or "update" you need
121 to set the result set class to "DBIx::Class::ResultSet::BitField" or to
122 a class which inherits from it.
123
124 __PACKAGE__->resultset_class('DBIx::Class::ResultSet::BitField');
125
126 update
127 $rs->update({ status => ['active'] });
128
129 This will update the status of all items in the result to "active". This
130 is done in a single SQL query.
131
132 search_bitfield
133 To search a result set for a specific value of the bitfield use
134 "search_bitfield".
135
136 You can either make a OR search:
137
138 my $new_rs = $rs->search_bitfield([ status2 => 1, status3 => 1 ]);
139
140 or AND:
141
142 my $new_rs = $rs->search_bitfield({ status2 => 1, status3 => 1 });
143
144 This method uses bitwise operators in SQL. Depending on your database it
145 is possible to create an index so the search is as fast as using a
146 single boolean column. =head1 AUTHOR
147
148 Moritz Onken <onken@netcubed.de>
149
150COPYRIGHT AND LICENSE
151 This software is Copyright (c) 2009 by Moritz Onken.
152
153 This is free software, licensed under:
154
155 The (three-clause) BSD License
156
157